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1.1 lEcoServiceProvider 


ECO Services 


1 Overview 


The ECO framework has been designed in such a way that business logic and framework logic are kept as separate as 
possible. For example, examining the generated source code for an ECO class will not reveal methods such as “Delete” or 
“Refresh”, as you might expect to find. Keeping framework methods out of our business classes is an important step towards 
making our source code more readable and manageable. Having a clear and almost invisible separation means that when 
we inspect the source code of our business classes we only see methods relating to the logical functioning of the class in 
question. This clearly makes our source code easier to understand, refactor, and debug. 


This document will cover two aspects of ECO services. First it will cover the most commonly used services implemented by 
the ECO framework itself, afterwards it will show how you may create and consume your own services and also show how 
separating functionality into services can improve your code by separating logic and making it easier to write unit tests. 
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1.1 lEcoServiceProvider 


The lEcoServiceProvider is an interface that is realized by the EcoSpace class and is the entry point for retrieving a 
reference to a previously registered service. The EcoSpace class itself additionally provides a shortcut to the default 
services, the following code snippet will check if there are currently any class instances that have modified persistent 
members which need to be saved to the data storage. 


if (EcoSpace .DirtyList. HasDirtyOb jects ( ) ) 


This same code could be achieved using the lEcoServiceProvider. GetEcoService<T>() generic method. This example is 
slightly longer than the previous example but illustrates how to retrieve a registered service without relying on the EcoSpace 
to have a short-cut property, for example when you register your own custom service. 


if (EcoSpace . GetEcoService<IDirtyListService> ( ) . HasDirtyOb jects ( ) ) 


Note: The EcoSpace class itself does not implement lEcoServiceProvider. The interface is actually implemented by another 
class which the EcoSpace owns an instance of. 


Retrieving services within a business class 

ECO business classes are designed so that they may be used in one or more applications, and therefore may be 
instantiated by one or more different descendants of EcoSpace. When retrieving services from within a business class 
method it is necessary to go via the lEcoServiceProvider interface. 


if 

(this . AsIOb ject ( ) . ServiceProvider .GetEcoService<IDirtyListService>() . HasDirtyOb jects ( ) ) 
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1 . AslObject() - This is the entry point to the "ECO world" from a business class. It accesses various support functionality 
for an object instance within the EcoSpace (they are not implemented by the class itself). The item of interest is the 

ServiceProvider property. 

2. ServiceProvider - This provides access to the lEcoServiceProvider in order to obtain references to registered services. 
This reference happens to also be the instantiated EcoSpace which owns the business class instance, however, it is 
recommended that additional features be implemented via services in order to prevent a strong dependency upon a 
specific EcoSpace type. 


1.2 Terminology 

As this document discusses both UML models and the source code produced there will be a number of terms which may be 
used to describe what is essentially the same thing, the term used will depend upon the context. For example, when 
describing Person. FirstName in the context of UML modeling the term "Attribute" would be used, when in the context of 
source code the term "Property" will be used. The following table is a list of terms and their meanings 




Description 

Attribute 

Property 

The term "Attribute" will never be used to refer to the System. Attribute class. System. Attribute will 
be referred to by its fully qualified name if necessary. 

Association 

end 

Single role 

Property 

A reference from one modeled class to another is always done via associations and not attributes. 
Each association has two ends in UML, and either two or one in source code depending on whether 
or not the association is navigable in both directions. 

A single role is an association end which links to at most one instance. 

Multi role 

Property 

A multi role is an association end which links to a list of instances, allowing it to hold zero to many 
references. 

Element 

Object 

instance 

Property 

This term is used to describe either an instance of a modeled object or one of its property values. 
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2.1 lExternalldService 
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Standard ECO services 


The following services are created and registered automatically whenever you create a new instance of an EcoSpace. These 
services are an interface to the features that ECO implements as standard such as persistence, in-memory transactions, and 
so on. 


A number of the ECO services have overloaded methods where parameters of the type lObject are replaced with a 
parameter of type lObjectProvider. lObject is what is known as an "object locator", the way in which ECO references 
instances of ECO business classes internally. lObject is obtained from an instance of a business class like so 


lObject ob jectLocator = personl .AsIOb ject () ; 


whereas the actual object instance is retrieved from the object locator like so 
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Person p = ob jectLocator . GetValue<Person> ( ) ; 


The business class itself implements lObjectProvider, so it then becomes possible to write code in either of the two following 
ways: 


//Passing lObject 

SomeE co Service . Do Something (personl . AsIOb ject ( ) ) ; 

//Passing the business class instance itself (lObjectProvider) 
SomeEcoService . DoSomething (personl ) ; 


When there are overloads for both parameter types I shall illustrate the lObjectProvider approach only, just to save from 
having to type .AslObjectQ needlessly. 


Note that when ECO services need to read or modify property values of object instances it does not require the use of 
reflection. How the values are manipulated depends upon whether or not the model specifies that the property has user code 
associated with it, additional code which needs to be executed in addition to manipulating the ECO cached values. 


Has 

user 

code 

Action taken 

True 

ECO will direct all property access via the object instance itself. To identify which property the service requires 
some auto-generated code is created in order to get/set property values via an integer index. 

False 

ECO will access the cache directly, bypassing the object instance completely. 
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2.1 lExternalldService 


Every business class instance within an EcoSpace is uniquely identifiable. Whether this is by an ECO generated object id, or 
a single/multi part primary key on a database. ECO requires a unique identifier so that it can perform persistence operations 
on the correct object when updating the database. Using the lExternalldService it is possible to either retrieve a string 
representation of an object instance's unique identifier, or to provide such a string representation and have ECO provide an 
object instance, if the object has not already been cached it will first be retrieved from the data storage. 


The 0bjectForid() and idForObject ( ) methods of the lExternalldService may be used to hold weak references to 
objects, or to pass business class instance references between different EcoSpace instances. This is especially prevalent in 
ECO powered web service / web application projects where you may wish to use a pool of EcoSpaces and therefore might 
not always working with the same EcoSpace instance across different page requests. If there is more than one EcoSpace in 
your web application’s/service's EcoSpace pool (which is recommended) then the flow in Figure 05 illustrates a likely 
scenario. 
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A user views an object in ViewPerson.aspx and then decides to edit that object, at which point they are redirected to 
EditPerson.aspx. Storing the Person object in a session is an incorrect approach because the Person instance belongs to 
EcoSpace A, whereas EditPerson.aspx was allocated EcoSpace B from the pool. Instead of holding ECO business class 
instances between page requests the web application/service should instead hold the "ID" of the object, which is retrieved 
using lExternalldService . idForObject () . The receiving page should retrieve an object instance from its allocated 
EcoSpace using the mirror method lExternalldService . Ob jectForld () . 


Although this service is used primarily for web applications/web services, there are many more possible applications. Any 
time the identification of an ECO business class instance needs to be stored in some way this service is the answer. 
Additionally when developing an ECO WinForms application you may wish to use multiple instances of your application's 
EcoSpace so that cached data is released as soon as an individual form is closed, the External IdService is an excellent way 
of passing object identities between these forms. 

//Sending the ID of an object in Forml 

string personID = EcoSpace . Externallds . IdForObject (person) ; 

SomeOtherForm. EditPerson (personID) ; 
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//Retrieving the object from the ID 

Person p = EcoSpace . Externallds . Ob jectForld (personID ) . GetValue<Person> ( ) ; 


Object ID structure 

The structure of these ID's is always in the format {Class id} ! {instanceiD} , an ID identifying the class, followed by an 
exclamation mark, followed by an ID identifying the instance itself. There are two points at which the ID for an object may 
change 


1. A new instance is persisted 

• Before - $new$!a791bdee-7cae-4cd6-882d-c983274a65ea!0 

• After -Oil 

2. The model is changed and the application rerun 

• Before - Oil 

• After -211 

Note: The instance ID is an integer by default, but may be another data type such as a Guid depending on how you 
configure your persistence. 


In the first case the ID is constructed by representing the class ID as the string $new$ followed by a Guid, and the instance 
ID as zero. The purpose of this is to prevent the ID of an new instance from being passed to another EcoSpace instance 
before it is persisted. When passing object references using external ID's the target EcoSpace is able to locate the object 
either in its cache or by fetching it from the data storage. If the ID being passed is a reference to a new instance then the 
target EcoSpace instance has no way of locating the object. Once the new instance has been persisted its ID will change to 
the format in the second example. 
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In the second example the ID is constructed by representing the class ID as an integer and the instance ID as the key the 
instance was assigned when it was first persisted to the data storage. The class ID is determined by locating the class in the 
model's list of classes. The list is sorted so that it remains in a predictable order, however, when the model is changed this 
can lead to classes appearing in the list or being removed from the list and can therefore cause the class index to change. 


External ID's were designed only to be used for short-term references in order to pass instance references between 
EcoSpace instances. Therefore it is not recommended that these ID's be held onto long term, for example 


• Storing the ID in a config file. 

• Storing the ID in a persistent property (associations are better suited for this purpose anyway). 

• Using the external ID as a parameter in a URL which might later be archived by search engines. 

It is possible to replace the ExternalldService if you wish to ensure that external ID's do not change when the model changes 
if you require it. This is a technique that will be demonstrated later in this document. See Replacing the ExternalldService (0 
see page 160) for details. 
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2.2 IStateService 


Whenever a new instance of a business class is created or an existing instance is modified ECO keeps track of these kinds 
of actions so that it later knows how to update the data storage. The IStateService provides a way of accessing these states. 


bool lsNew(IObjectProvider obj) 

If the ECO business class instance passed has been created and not yet persisted to the data storage this will return true. 
Once the object has been persisted this method will always return false, even if the object is later modified and requires its 
changes to be persisted. 


bool lsDirty(IProperty property) 

If lsNew() returns true for the object instance that owns the property then this method will always return true. If the member 
in question has not been modeled as persistent (it is transient or derived) then this method will return false. 


If the member has been modeled as persistent and has a change which needs updating to the data storage this method will 
return true. In the case of simple members such as Int32 and String the result will depend simply on whether or not a change 
has been made. When the member is an association it is not considered dirty (modified) if it is not embedded. Here are 
some scenarios which illustrate this last point: 


1. Neither end is marked as embedded in the model. An additional table will be created in the database with the name of the 
association "DriverCurrentVehicle". 
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0..1 

DriverCurrentVehicle 0 1 



CurrentDriver 


J 


CurrentVehicle 

J 


Driver driver = new Driver (EcoSpace) ; 

Vehicle vehicle = new Vehicle (EcoSpace) ; 

//Get the property references for use with ECO services 

IProperty driverCurrentVehicleProp = driver . AsIObject (). Properties [ "CurrentVehicle "] ; 
IProperty vehicleCurrentDriverProp = vehicle . AsIObject (). Properties [ "CurrentDriver " ] ; 

//Both return true because the object itself is new 

Debug .WriteLine (EcoSpace .States.IsDirty (driverCurrentVehicleProp) ) ; 

Debug .WriteLine (EcoSpace .States.IsDirty (vehicleCurrentDriverProp) ) ; 

EcoSpace . UpdateDatabase ( ) ; 
driver . CurrentVehicle = vehicle; 

//Both return false because neither end is embedded 

Debug . WriteLine (EcoSpace .States.IsDirty (driverCurrentVehicleProp) ) ; 

Debug . WriteLine (EcoSpace .States.IsDirty (vehicleCurrentDriverProp) ) ; 


2. The Driver end of the association is marked as embedded. The Vehicle table in the database will have an additional 
column named "CurrentDriver" which holds the ID of the driver instance. 
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Driver 


0..1 

CurrentDriver 


DriverCurrentVehicle 


CurrentVehicle 


J 


Vehicle 


Driver driver = new Driver (EcoSpace) ; 

Vehicle vehicle = new Vehicle (EcoSpace ) ; 

//Get the property references for use with ECO services 

IProperty driverCurrentVehicleProp = driver .AsIObject (). Properties [ "CurrentVehicle" ] ; 
IProperty vehicleCurrentDriverProp = vehicle . AsIObject (). Properties [ "CurrentDriver "] ; 

//Both return true because the object itself is new 

Debug . WriteLine (EcoSpace .States.IsDirty (driverCurrentVehicleProp) ) ; 

Debug . WriteLine (EcoSpace .States.IsDirty (vehicleCurrentDriverProp) ) ; 

EcoSpace . UpdateDatabase ( ) ; 
driver . CurrentVehicle = vehicle; 

//Returns false because it is not embedded 

Debug .WriteLine (EcoSpace .States.IsDirty (driverCurrentVehicleProp) ) ; 

//Returns true because the ID of the Driver is embedded into this class ' s table 
Debug . WriteLine (EcoSpace .States.IsDirty (vehicleCurrentDriverProp) ) ; 


3. The Order end of the association is marked as embedded. The OrderLine table in the database will hold the column 
referencing which order it belongs to. 



4. Neither end of this association may be embedded because both ends are multiple (not all databases support multi-values 
in a single column). An additional table is created in the database with the name of the association (FoodLikedBy) in order 
to maintain the associations. 


j 


Pei son 


0..* 

FoodLikedBy 

0 ..* 


LikedBy 


FoodLiked 

j 


Food 


Person wallis = new Person (EcoSpace) ; 

Food cheese = new Food (EcoSpace) ; 

//Get the property references for use with ECO services 
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IProperty personFoodLikedProp = wallis . AsIObject (). Properties [ "FoodLiked" ] ; 
IProperty f oodLikedByProp = cheese . AsIObject (). Properties [ "LikedBy" ] ; 

//Both return true because the object itself is new 

Debug .WriteLine (Eco Space .States.IsDirty (personFoodLikedProp) ) ; 

Debug .WriteLine (Eco Space .States.IsDirty ( f oodLikedByProp) ) ; 

EcoSpace . UpdateDatabase ( ) ; 
wallis . FoodLiked . Add ( cheese) ; 

//Returns false because neither end may be embedded 

Debug . WriteLine (EcoSpace .States.IsDirty (personFoodLikedProp) ) ; 

Debug .WriteLine (EcoSpace .States.IsDirty ( f oodLikedByProp) ) ; 


bool lsDirty(IObjectProvider obj) 

If any of the properties for the passed object instance are considered dirty or the object instance is new or marked as deleted 
then this method will return true, otherwise there are no changes to persist to the data storage and this method will return 
false. 


Person person = new Person (EcoSpace) ; 

//Will return true because the object is new 
Debug .WriteLine (EcoSpace .St at es.IsDirty( person) ) ; 

EcoSpace . UpdateDatabase ( ) ; 

//Will return false, the object remains unaltered since it was persisted 
Debug .WriteLine (EcoSpace .St at es.IsDirtyt person) ) ; 

person . AsIObject ( ) . Delete () ; 

//Will return true, the object has not been removed from the data storage since deleted 
Debug .WriteLine (EcoSpace .St at es.IsDirty( person) ) ; 

EcoSpace . UpdateDatabase ( ) ; 

//Will return false, the object cannot be dirty now that it no longer exists 
Debug .WriteLine (EcoSpace .St at es.IsDirtyt person) ) ; 
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2.3 IDirtyListService 

Whenever a persistent object is created, modified, or deleted, it is considered to be"Dirty"; this means that it has in some 
way been altered. This Dirty state is an indication that the data storage needs to be updated in order to reflect the changes 
made to the object instance in question. 


Using the IDirtyListService interface the dirty list service enables the developer to obtain a list of objects that have been 
modified. Note that the "Dirty" state is reserved for persistent objects only, object instances of a class marked as Transient in 
the model are never saved to the persistence storage and therefore cannot have such a state. Additionally, if the EcoSpace 
has no persistence defined then all classes are considered to be Transient regardless of how they have been defined in the 
model, in such a case the IDirtyListService will never hold any object references. 


lObjectList AIIDirtyObjects() 

This method returns an lObjectList containing an lObject for each dirty object held within the EcoSpace. This list is 
immutable, meaning that if you try to modify it using Remove() for example a System. InvalidOperationException will be 
thrown. The size of this list will alter as more objects become dirty, the data storage is updated marking some objects as 
non-dirty, or as a result of objects becoming dirty/non-dirty due to in-memory transactions being rolled back or reapplied - 
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StartTransaction, RollbackTransaction, 


see lUndoService (0 see page 9). 


bool HasDirtyObjectsO 

If AllDirtyObjects () . Count is greater than zero then this method will return true, otherwise it will return false indicating 
that there are no dirty objects to persist to the data storage. 


void Subscribe(ISubscriber subscribe) 

Passing an instance of ISubscriber to this method will cause the iSubscriber .Receive method to be executed whenever 
the number of objects held in the AllDirtyObjects () list alters. This is a useful global hook to perform tasks on objects 
that have been modified, for example to provide on-screen validation. 


2.4 lUndoService 


Using the lUndoService the programmer is able to perform in-memory transactions on objects within the EcoSpace. These 
transactions may be committed, reversed, or reapplied at any point ensuring that if an operation fails the state of all affected 
objects is returned to a specific state. 


To use a classic example; if a funds transfer is initiated from bank account "A" to bank account "B" two operations must take 
place. The balance of account "A" must decrease by the transaction value and the balance of account "B" must increase by 
the transaction value. This kind of atomic operation has been available in all good databases for quite some time now, but 
the ECO undo service allows the same kind of atomic operation to be performed in-memory as well, eliminating the need to 
reload object contents from the data storage if you wish to abandon a set of changes. 
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The undo service provides two main pieces of functionality. Firstly it provides named undo-blocks; changes within the undo 
block may be reversed or reapplied repeatedly. Secondly it provides in-memory transaction support, which internally uses 
the undo-block functionality to provide nested StartTransaction , RollbackTransaction, and CommitTransaction 
methods. 


The undo blocks are also affected by the persistence service (0 see page 133) whenever an update is performed. 


2.4.1 StartTransaction, RollbackTransaction, and 
CommitTransaction 


This first example will demonstrate how to perform an in-memory transaction on a number of objects within the EcoSpace. 
The example will transfer a given amount of money from one bank account to another, it will adjust the CurrentBalance of 
each account and additionally create a transaction object to record the transfer. If an exception of some kind occurs within 
the transfer method then all changes will be rolled back, otherwise the in-memory transaction will be committed. 
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Undo blocks 


BankAccount 

i 

AccountDebited Transf ersOut 

1 0..* 

FundsTransfer 

J 

attr Unites 

+ Balance: decimal 

attr Unites 

+ Amount: decimal 



opei ations 

+ TransferFundsf..') 

AccountCredited Transf ersln 

1 0..* 


public class FundsTransfer 

{ 

public static void Transf erFunds ( IEcoServiceProvider serviceProvider , BankAccount 
debitAccount , BankAccount credit Account , decimal amount) 

{ 

//Perform parameter validation here 

lUndoService undoService = serviceProvider . GetEcoService<IUndoService> () ; 
undoService . StartTransaction ( ) ; 

try 

{ 

FundsTransfer transfer = new FundsTransfer (serviceProvider) ; 

transfer . AccountDebited = debitAccount; 

transfer . AccountCredited = creditAccount ; 

transfer .Amount = amount; 

debitAccount . Balance -= amount; 

creditAccount . Balance += amount; 

//Perform overdraft validation etc here 

} 

catch 

{ 

undoService . RollbackTransaction ( ) ; 

throw; 

} 

undoService . CommitTransaction ( ) ; 

} 

} 
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1. A reference to the lUndoService is obtained. 

2. An in-memory transaction is started. 

3. A new FundsTransfer object is created to record the transfer. 

4. The FundsTransfer object is associated with the debit and credit accounts. 

5. The balances of both the credit and debit accounts are modified. 

If all goes as expected the EcoSpace will have a new FundsTransfer object to persist to the data storage along with modified 
account balances. If any exception is thrown during the operation the in-memory transaction is rolled back restoring the 
EcoSpace to its former state, the FundsTransfer object will no longer exist and the two accounts in question will remain 
unaltered. 


2.4.2 Undo blocks 


Undo blocks provide a mechanism similar to transactions, in fact the transaction mechanism internally uses undo blocks. 
Whenever a modification is made to an ECO element (object / property) ECO will check if there is an active undo block. If an 
undo block is found, and the element in question is not already in the active undo block, ECO will record the elements 
original value in the undo block. In the case of a property the original value will be recorded, in the case of an lObject its 
state will be recorded (new, existing, deleted). 
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Undo blocks 



Holding a collection of elements plus their original states allows the changes recorded in an undo block to be reversed, 
restoring the EcoSpace to the exact state it was in at the point the undo block was created. The undo service may hold 
multiple undo blocks, only the topmost undo block is considered to be active therefore changes made within the EcoSpace 
will always be applied only to the topmost undo block, new undo blocks are always placed at the top of the undo list. This 
makes it possible to have multiple separate transactions being performed within the EcoSpace at the same time, each with 
the ability to be independently reversed or reapplied. 


One example use of the undo service is when working with multiple forms against a single EcoSpace instance. Each form 
could own its own undo block and move it to the top of the list (thus making it active) whenever that form is focused. This 
would make it possible to track changes made by an individual form and then undo / redo those changes or update the data 
storage with those changes only. Note that it is recommended to have one EcoSpace instance per form whenever possible. 


Creating an undo block 

Undo blocks in ECO are identified using a unique block name. Although it is possible to hold a reference to an undo block 
using an lUndoBlock it is only advisable to hold such a reference for a short period of time; only as a local variable for 
example. The reasoning is quite simple, undo blocks may be removed from the undo service completely (effectively 
"committed"), accessing the undo block by name will correctly return null whereas holding onto an lUndoBlock reference 
would result in your application performing operations on an undo block that is no longer valid. 


To ensure that block names are unique, the undo service provides the GetuniqueBiockName method. Executing this 
method will provide your application with a block name that is guaranteed to be unique. 


int i = 1; 
while (i++ <= 3) 

{ 

string uniqueName = EcoSpace . Undo . GetuniqueBiockName ( "Test ") ; 
EcoSpace . Undo . StartUndoBlock (uniqueName) ; 

MessageBox . Show (uniqueName ) ; 

} 
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Working with the undo service 


In this example the application creates three undo blocks. Rather than hard-coding the block name as "Test" the application 
asks the undo service to return a unique name using "Test" only as a suggested name. The output of the program as each 
iteration of the loop is executed is as follows; Test, Testl, Test2. 


Note that if the application makes a modification to an object in the EcoSpace and there are no undo blocks present ECO 
will automatically create an undo block named "Unnamed", trying to create an undo block with a name that is already in use 
will result in a System. InvalidOperationException being thrown. 


2.4.3 Working with the undo service 

Undo operations 

Using the undoBiock method it is possible to reverse any changes that have been made since the undo block was 
activated; i.e. when it became the undo block at the top of the UndoList. Calling undoBiock will perform the following actions 


1. Move the block into the RedoList 

2. Store the new values instead of the original values, so that the changes may be reapplied later if necessary 

3. Restore the original values. This includes modified members, and also created / deleted object instances 





2.4 lUndoService 
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Working with the undo service 


You may also use the undoLatest method to undo the block at the top of the UndoList. 


Redo operations 

Once a block is in the RedoList it is possible to reapply its changes using the RedoBiock method. Whereas an undo 
operation reinstates the original state a redo operation will reinstate the modifications made. Calling RedoBiock will perform 
the following actions 


1 . Move the block back to the UndoList 

2. Store the very original values in case undoBiock is executed again 

3. Restore the modified values 



Person 


FirstName = John 
LastName * Mom Smith 
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#region Code from undo example 
Person personl = new Person (EcoSpace) ; 
personl . FirstName = "Peter"; 
personl . LastName = "Morris"; 

EcoSpace . Undo . StartUndoBlock ( "D" ) ; 

//Update undo block D with LastName=Morris 
personl . LastName = "Smith"; 

//Restore LastName to Morris 
//Record modified LastName as Smith 
//Move block to RedoList 
EcoSpace . Undo . UndoBiock ( " D " ) ; 

#endregion 

//Restore modified value LastName=Smith 
//Record original value LastName=Morris 
//Move block back to UndoList 
EcoSpace . Undo . RedoBiock ( " D " ) ; 


You may also use the RedoLatest method to redo the block at the top of the RedoList. 
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Working with the undo service 


Moving blocks 

Blocks in the UndoList/RedoList may be rearranged. The purpose of this is to bring a different undo block to the top of the list 
in order to make it active. As mentioned earlier this is useful for example if you wish to track changes made by the user on a 
form by form basis so that they may be undone/redone independently of each other. Both the UndoList and RedoList 
implement a MoveBlock (int currentlndex, int newlndex) method. 


There is a restriction which must be adhered to when moving blocks. When multiple blocks A,B,C contain information about 
the same element it makes sense logically to undo changes only in the order C,B,A and to redo changes only in the order 
A,B,C. To enforce this rule ECO will always attempt to move the specified block to the top of its list before either undoing or 
redoing its contents. If any blocks above the block being moved contain any common elements the process is aborted with a 
System. InvalidOperationException. The following example illustrates this point 


EcoSpace . Undo . StartUndoBlock ( "A" ) ; 

Person personl = new Person (EcoSpace) ; 
personl . FirstName = "Peter"; 

/ /Create a new block at the top of the list 
EcoSpace . Undo . StartUndoBlock ( "B" ) ; 
personl . FirstName = "John"; 

//Uncreate personl - this cannot be done due to undo block B 
EcoSpace . Undo . UndoBlock ( "A" ) ; 

//Revert personl . FirstName to "Peter" 

EcoSpace . Undo . UndoBlock ( "B" ) ; 


In this example it is not possible to undo the changes in block A first because block B is above it and contains a common 
element. If this were permitted it would result in block B remaining in the list holding undo information about an object that no 
longer exists. To determine whether or not it is possible to move a block to a specific location use the CanMoveBiock (int 
currentlndex, int newlndex) method of either the UndoList or RedoList. If your intention is to undo or redo a block 
rather than to simply move it then you can use either CanRedoBlock (string blockName) or CanUndoBlock (string 
blockName) . 
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To move a block to the top of the UndoList/RedoList you may use the lists’ MoveToTop (string blockName) methods. 


Merging blocks 

Both the UndoList and RedoList contain a MergeBlocks (string destinationBlockName, string 
sourceBiockName) method. When two blocks are merged the information stored in the source block is added to the 
destination block and then the source block is removed from the list. If both blocks contain information one of these pieces of 
information must take priority. The following table describes how this priority is determined 


List used 

Action taken 

UndoList 

The oldest information takes priority, the change that occurred latest is discarded. 

RedoList 

The newest information takes priority, the change that occurred earliest is discarded. 


As with moving blocks there is a similar restriction. When two blocks are merged ECO will check the contents of each block 
between them, if any of those blocks contain an element common to either the source or destination block then the merge 
will not be permitted. The method CanMergeBiock (int currentlndex, int newlndex) will indicate whether the 
merging of two undo blocks is possible. 
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Working with an undo block 


Removing blocks 

Using undoBlock and RedoBlock removes the undo block from its owning list but also inserts it into the opposite list. 
There are two ways in which an undo block is removed from a block list permanently, without being moved to another list. 


1 . The data storage is updated - Any block containing changes for any of the objects updated to the data storage will be 
removed automatically. 

2. Manual removal - Executing a list's RemoveBiock (string biockName) method will remove the block with the 
specified name, executing ciearAiiundoBiocks will clear both the UndoList and the RedoList. 

Once a block has been removed it cannot be manually re-added to the undo mechanism. 


2.4.4 Working with an undo block 


Undo blocks expose a limited number of features via the lUndoBlock interface. 


Retrieving an undo block 

An lUndoBlock reference may be obtained from either the UndoList or the RedoList either by name or index. 


private void buttonl_Click (object sender, EventArgs e) 

{ 

EcoSpace . Undo . StartUndoBlock ( "In UndoList " ) ; 

//Create a block and move it to the RedoList 
EcoSpace . Undo . StartUndoBlock ("In RedoList " ) ; 

EcoSpace . Undo . UndoLatest ( ) ; 

//Show by name 

ShowBlockName (EcoSpace . Undo .UndoList ["In UndoList " ] ) ; 
ShowBlockName (EcoSpace . Undo . RedoList ["In RedoList " ] ) ; 

//Show by index 

ShowBlockName (EcoSpace . Undo . UndoList [ 0 ] ) ; 

ShowBlockName (EcoSpace . Undo . RedoList [ 0 ] ) ; 

//Non-existent by name 

ShowBlockName (EcoSpace . Undo . RedoList [ "This does not exist"]); 
//Non-existent by index 

ShowBlockName (EcoSpace . Undo . RedoList [ 99 ] ) ; 


private void ShowBlockName ( lUndoBlock undoBlock) 
{ 

if (undoBlock == null) 

MessageBox . Show ( "<null>" ) ; 

else 

MessageBox . Show (undoBlock . Name ) ; 
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Retrieving an undo block using an invalid name or index will return null. 
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Members of lUndoBlock 

• Name - The name give to the undo block. 

• ContainsChanges - Returns false if the undo block is empty, otherwise returns true. 

• GetChangedObjects() - Returns an lObjectList. Each lObject is the identity of the object instance that has been modified. 

• Subscribe(ISubscriber subscriber) - The subscriber is notified whenever the contents of the undo block change, when the 
undo block moves between the RedoList and UndoList, or the when undo block is removed from the undo service 
altogether. 


2.5 lObjectFactoryService 

This service provides an alternative way of creating instances of modeled classes. Ordinarily a new instance of a modeled 
class is created in an application like so 


//EcoSpace implements IEcoServiceProvider, so we can pass the EcoSpace 
OrderLine newLine = new OrderLine (EcoSpace ) ; 

CurrentOrder . Lines .Add (newLine) ; 


or to create an instance from a method of another modeled class like so 


//Business classes don 't have an EcoSpace, so we pass the IEcoServiceProvider 
OrderLine newLine = new OrderLine (this .AsIOb ject (). ServiceProvider) ; 
this . Lines .Add (newLine) ; 
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Creating a new object instance is so trivial that it may seem unnecessary to have a service for this purpose, however, the 
object factory service makes it easy to create instances of modeled classes when the type is not know until runtime, or is 
determined by reading model information. 


Creating an object instance 

The first approach is the one most similar to the previous example. An instance will be created by passing the System.Type. 


IOb jectlnstance instance = EcoSpace . Ob jectFactory . CreateNewOb ject (typeof (Person) ) ; 
Person personl = instance . GetValue<Person> () ; 


First an lObjectlnstance is created by instructing the object factory service to create a type of Person. Next the Person 
instanced is retrieve from the lObjectlnstance object locator. Note that the lObjectlnstance reference may be used as a 
parameter for various other service methods; it is also possible to use personl .AslObjectQ to retrieve the lObjectlnstance. 


The second approach is to use a string to identify the name of the class to create. Unlike the previous approach this 
approach will not cause a compile error if you change the name of the Person class. 

lObjectlnstance instance = EcoSpace . Ob jectFactory . CreateNewOb ject ("Person") ; 


The final approach creates an instance identified by an ICIass. An ICIass is an interface holding information about a specific 
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class in the model, this instance holds additional information regarding persistency etc. This is covered in the type system 
service (0 see page 1 47) section of this document. 



In the model above the Person class may now contain multiple pieces of contact information. The Contactlnformation class 
itself is abstract so cannot be instantiated, the subclasses TelephoneNumber, EmailAddress, and PostalCode are all 
concrete classes and therefore may be instantiated and associated with a person. When the user interface offers the user 
the opportunity to add some contact information for a Person it would be nice if the possible types were determined 
automatically rather than having to hard code them and have to remember to update the code each time a new kind of 
contact information was added to the model. This is where the ICIass comes in. The following code example will show how 
to perform this task; it will use some code from a service which has not get been covered so feel free to skip directly to the 
point in the example where the instance is created. 


2 



PostalAddress 

TelephoneNumber 


private void ButtonNewContact Inf ormation_Click (object sender, EventArgs e) 
f 

//Clear the context menu 

ContextCreateContactlnformation . Items . Clear ( ) ; 

//Find the base ICIass 

ICIass contactlnformationClass = 

EcoSpace . TypeSystem. GetClassByType (typeof (Contactlnformation) ) ; 

//Recursively add all types 
AddClassToMenu (contactlnformationClass) ; 
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//Show the menu 

Point popupPoint = new Point (ButtonNewContactlnformation .Width / 2, 
ButtonNewContactlnformation . Height / 2); 

ContextCreateContactlnformation . Show (ButtonNewContactlnformation, popupPoint ) ; 


private void AddClassToMenu (IClass contactlnformationClass) 

{ 

//If this is not abstract then create a menu item 
if ( ! contactlnformationClass . IsAbstract) 

{ 

var menultem = new ToolStripMenuItem ( contact Inf ormationClass . Name) ; 
Context CreateCont act Inf ormat ion . Items . Add (menultem) ; 
menultem. Tag = contactlnformationClass; 
menultem . Click += MenuItemCreateClass_Click; 

} 

//Now recursively add any sub classes 

foreach (IClass subclass in contactlnformationClass . SubTypes) 
AddClassToMenu (subclass) ; 


private void MenuItemCreateClass_Click (object sender, EventArgs e) 

{ 

//Normally we would pass the type to a specific form to edit 
//but for this example we will just add directly to the list 
ToolStripMenuItem menultem = (ToolStripMenuItem) sender; 

IClass contactlnf oClass = ( IClass ) menultem . Tag; 

//Create the new instance based on IClass 

10b jectlnstance instance = EcoSpace . Ob jectFactory . CreateNewOb ject (contact Inf oClass ) ; 
Contactlnformation newContactlnfo = instance . GetValue<ContactInformation> () ; 

Cur rent Per son . Contactlnformation . Add (newContactlnfo) ; 
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2.6 IVariableFactoryService 

This service enables the develper to create a number of Element based objects which may then be used in various different 
parts of the ECO framework. The Element interface is prevalent throughout the ECO framework as it is used to represent 
instances of modeled classes (lObject ultimately descends from Element), property values (Int32, String, etc), and 
association ends (lObjectList). These variables may then be used in various other services, for example the OCL Service 
may evaluate OCL expressions which include variable names (a bit like parameterized queries). Although in most 
circumstances it is anticipated that the developer will want to use a handle for declaring variables this service allows you to 
create variables in code, which is useful in methods of modeled classes where you have no design surface onto which to 
drop a VariableHandle etc. 


Creating a constant 

A constant is most useful when adding an event derived column to an ECO handle. One very useful implementation of this 
functionality is when you have a many to many association between two classes and wish to show the user a selection of 
options with a check box, checking the check box will add the item to the association whereas unchecking the check box will 
remove the option from the association. 
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Extras 

BookingOption 

^ Booking 

Bookings 

0 ..* 

0 ..* 

attributes 




+ Description: string 


The model above allows a single instance of BookingOption to be associated with many bookings, and for a booking to have 
many BookingOption instances (extras). The following user interface displays a booking form with a list of all available 
BookingOption instances rather than only the ones associated with the booking in question. 


■9 Booking extras for #123542 1 ^ I 151 



Inc 

Description 


si 

Additional baggage allowance 

J 

0 

Executive dub access 


H 

First dass 


□ 

Free transfer 


1. An expression handle was added with the expression "BookingOption. alllnstances". 

2. The columns were edited and a new EventDerivedColumn was added using the drop down list on the Add button. 

3. The DeriveValue and ReverseDeriveValue events on this expression handle were implemented like so 
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private void ehBookingOptions_DeriveValue (object sender, DeriveEventArgs e) 

{ 

//Get the BookingOption in question 

BookingOption option = e . RootElement . GetValue<BookingOption> ( ) ; 

switch (e.Name) 

{ 

case "Included": 

//Result is true if this option is in CurrentBooking . Extras 
bool islncluded = CurrentBooking . Extras . Contains (option) ; 

//Create the boolean constant and specify it as the result 
e . ResultElement = Eco Space . VariableFactory . CreateConstant (islncluded) ; 

//Additional : We need to tell ECO to update the ticks in the boxes whenever 

//the size of CurrentBooking . Extras changes 

W/01: Get the IProperty for CurrentBooking . Extras 

int proplndex = Booking . Eco_LoopbackIndices . Extras_MemberIndex; 

IProperty extrasProperty = 

CurrentBooking . As I Ob ject ( ) . Properties . Get By Loopback Index (proplndex) ; 

//02: Subscribe to it 

extrasProperty . SubscribeToValue (e . Re subscribe Subscriber) ; 

break; 

default : 

throw new NotlraplementedException (e.Name); 



private void ehBookingOptions_ReverseDeriveValue (object sender, ReverseDeriveEventArgs e) 

{ 

//Get the BookingOption in question 

BookingOption option = e . RootElement . GetValue<BookingOption> () ; 

switch (e.Name) 

{ 

case "Included": 
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bool islncluded = (bool) e .Value; 

//Add or remove it from the list. This will update the 
//UI automatically because when we derived the value we 
//subscribed to CurrentBooking . Extras 
if (islncluded) 

CurrentBooking .Extras . Add (option) ; 

else 

CurrentBooking . Extras . Remove (option) ; 

break; 

default : 

throw new NotlmplementedException (e .Name) ; 

} 

} 


Creating a list of objects 

When creating an lObjectList you have the option of either allowing lObject instances representing any modeled class, or 
ones which represent a specific modeled class and its subclasses only. To create an untyped object list you would use the 
CreateUntypedObjectList (bool allowDuplicates ) method, this kind of list is useful when you wish to update the 
data storage with a collection of objects rather than updating all dirty objects. 


//Create three people 

Person personl = new Person (EcoSpace) ; 

Person person2 = new Person (EcoSpace ) ; 

Person person3 = new Person (EcoSpace ) ; 

//Create the object list 

IVariableFactoryService vfs = EcoSpace . VariableFactory; 
lObjectList ob jectsToPersist = vfs . CreateUntypedObjectList (false) ; 

//Add only the locators for personl and person3 
ob jectsToPersist .Add (personl .As IObject ( ) ) ; 
ob jectsToPersist .Add (person3 .As IObject ( ) ) ; 

//Now update the data storage with only those two objects 
EcoSpace .Persistence. UpdateDatabaseWithList (ob jectsToPersist ) ; 
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To create a typed object list you would use either 

• CreateTypedObjectList(Type type, bool allowDuplicates) 

• CreateTypedObjectList(ICIass umICIass, bool allowDuplicates) 

The first accepts a .NET Type whereas the second accepts an ICIass representing the modeled class to use, this ICIass 
reference may be obtained from the model at runtime using the type system service (0 see page 147). This kind of list is 
useful when you require a strongly typed list of objects, for example if you wish to create a list in code rather than using an 
OCL (0 see page 22) expression and then present that list to the user via a ReferenceHandle. In this case a grid is 
connected to rhRoot which has its StaticValueTypeName property set to Collection (Person) . 


//Create three people 

Person personl = new Person (EcoSpace ) ; 
personl . FirstName = "Peter"; 
personl . LastName = "Morris"; 

Person person2 = new Person (EcoSpace ) ; 
person2 . FirstName = "John"; 
person2 . LastName = "Smith"; 

Person person3 = new Person (EcoSpace ) ; 
person3 . FirstName = "Fred"; 
person3 . LastName = "Jones"; 
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/ /Create the object list 

IVariableFactoryService vfs = EcoSpace . VariableFactory; 

IObjectList ob jectsToPresent = vfs . CreateTypedOb jectList (typeof (Person) , true); 

//Add only the locators to the list 
ob jectsToPresent .Add (personl . AsIOb ject ( ) ) ; 
ob jectsToPresent .Add (person2 .AsIOb ject ( ) ) ; 
ob jectsToPresent .Add (person3 .AsIOb ject ( ) ) ; 
ob jectsToPresent .Add (person2 .AsIOb ject ()); 
ob jectsToPresent .Add (personl .AsIOb ject ( ) ) ; 

//Now present the list to the user interface 
rhRoot . SetElement (ob jectsToPresent) ; 



Creating a variable list 

A variable list is a collection of values cross referenced by name. Variable lists are useful when you need to execute an OCL 
expression which refers to multiple object instances. For example the following expression would select all bookings for a 
specific customer and flight combination, note that the prefix var_ is purely optional and only used here for clarity 
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PropertyBooking . alllnstances->select ( customer = var_Customer) ->select (flight = 
var_F light ) 


The above expression could have been implemented with constants rather than variables, in fact when you create a variable 
list you may add constants or variables. Flowever, variable lists may also be used in a similar way to how query parameters 
work in a SQL statement within a standard DB application. 


IVariableFactoryService vfs = EcoSpace .VariableFactory; 
//Create three people 

Person personl = new Person (EcoSpace) ; 
personl . FirstName = "Peter"; 
personl . LastName = "Morris"; 

Person person2 = new Person (EcoSpace) ; 
person2 . FirstName = "John"; 
person2 . LastName = "Smith"; 

Person person3 = new Person (EcoSpace ) ; 
person3 . FirstName = "Fred"; 
person3 . LastName = "Jones"; 

EcoSpace . UpdateDatabase ( ) ; 

//Create the variable 

IModif iableVariableList variables = vf s . CreateVariableList ( ) ; 
IElement lastNameVar = vf s . CreateVariable (typeof (string)); 
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variables . Add ( "var_LastName" , lastNameVar) ; 

//Define a list of values to loop through 

string[] lastNames = new string [ ] {"Morris", "Smith", "Jones"}; 

//Define the OCL expression using var_LastName 

string ocl = "Person . alllnstances->select ( lastName = var_LastName) " ; 

//Now loop through each value 

foreach (string currentLastName in lastNames) 

{ 

//Set the value of the variable 
lastNameVar .AsObject = currentLastName; 

//Execute the query 

IList<Person> people = EcoSpace . OclPs . Execute (null, variables, ocl, -1, 
0 ) . GetAsIList<Person> ( ) ; 

//Now show the result 

foreach (Person currentPerson in people) 

{ 

string message = string . Format ("{ 0 } -> {1} {2}", 
currentLastName, 
currentPerson . FirstName, 
currentPerson . LastName ) ; 

MessageBox . Show (message) ; 

} 

} 
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The above example creates a variable of type System. String, the return value of CreateVariable is an Element. The variable 
is then added to a variable list with the name var_LastName. Within the loop it is possible to set the value of the variable by 
setting lastNameVar .AsObject. When the OCL expression is evaluated the text var_LastName will substituted with the 
variable's value instead. Just like query parameters this approach prevents the developer from having to escape special 
query characters in order to ensure the query always remains valid (see SQL injection 
http://en.wikipedia.org/wiki/SQL_injection, see also http://xkcd.com/327). 


The important parameters being passed to OclPs .Execute are variables and ocl. The other parameters will be 
explained in the IQcIPsService (a see page 25) section. 


2.1 Query services 

These ECO services process queries that are based on the Object Constraint Language (OCL) in order to retrieve 
information from the ECO cache. When an EcoSpace is persistent ECO will also translate the OCL query into the query 
language of the data storage (usually SQL) to ensure that the data necessary to process the query is loaded into the ECO 
cache. 


As not all OCL operations are supported by all target data storages OCL query support is cleanly separated into three 
distinct services. Each service is described in a particular order; the service being described is capable of processing a 
superset of any previously described OCL services. 


Format of OCL expressions 

All OCL expressions start with a root context. This context may be a modeled class type, an instance of a modeled class, a 
single element (such as an integer or string), or a collection. The following expression shows how to use the modeled 
Person class to start the expression, and return all instances of that class: 

Person. alllnstances 
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The above expression would result in a collection of Person instances. From this context it is possible to either perform a 
collection operation or a member operation. Like many OOP languages to identify a member the context and member name 
are separated by a period, collection operations are separated by the token -> 

//Returns the first person in the collection 
Person. alllnstances->first 

//Returns the DateOfBirth of the first person in the collection 
Person. alllnstances->first . dateOf Birth 

When a member name is appended directly to a collection the OCL parser will automatically iterate through each element 
within the collection and return a collection of the member specified. 

//Returns a collection of DateTime, one for each person in the collection 
Person. alllnstances. dateOf Birth 


OCL expressions with a specific context 

It is possible to evaluate OCL expressions on an individual instance of a modeled class. For example when defining OCL 
based validity constraints on a class those expressions would be evaluated in the context of an instance of that class. When 
evaluating against an instance the context is assumed to be that instance. The keyword self may be used within the 
expression to identify the root object 

self . dateOfBirth 

The self keyword is case sensitive and must always be written in lowercase. When evaluating an expression against a root 
this does not mean that the OCL expression must start with that root object. At any point within an OCL expression it is 
possible to reference a modeled class by its name and use that as the context of the expression. 

//using self other than as the context of the expression 
//self references an instance of Customer 
Booking . alllnstances->select (bookedBy = self) 

//Returns the same result as 
self . bookings 

The above two expressions will return the same result. The first expression is less efficient than the second as it will first 
retrieve all instances of Booking and then filter the list down to only those booked by the root object (Customer), the second 
expression uses the Customer as the context of the expression to find its bookings which results in retrieving only bookings 
assigned to this Customer and not having to filter the list afterwards. 
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Changing context within an expression 


In the previous examples you can see that you can switch the context to a class despite having a root object to evaluate 
against. It is in fact possible to switch the context to a class at any point within an expression 


self . eventsAttended->intersection ( 

Event . allInstances->orderDescending (date) ->subSequence (1, 5) 

) 


This more complicated expression uses a Customer as the root to evaluate the expression against (and therefore by default 
the initial context). It switches the context to all events attended by that customer and then filters that event list down to 
include only the last 5 events held. The last 5 events held are determined by selecting all Event instances, ordering the 
collection by their date (descending), and then selecting the top 5. 
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Members with the same name as a class 


Event 0 


Bookings 


Booking 


Bookings 


1 

-O 


Bookings 


Payment 1 


Payment 


In this simple model it makes sense that the association from a booking to the Payment class should be named "Payment", 
the association from a booking to the event should be named "Event", and that the association from Booking to Customer 
should be named "Customer". 


When evaluating an expression such as the following (using Customer as the root) 

bookings->orderBy (date) 

it is quite clear that the start of the expression refers to the member Customer.Bookings. When evaluating an expression that 
starts with a member that has the same name as a class in your model it is not clear whether you intend the OCL evaluator 
to interpret the token as the member name or if you intend to switch the context to another class. 

//Error - Event is interpreted as a class 
event . cancelled 

In such a case you would precede the member name explicitly with the keyword self. 

self . event . cancelled 

By now you may have noticed that all of the examples in this section use a lowercase initial letter for members and an 
uppercase initial letter for class names. This is a standard in the OCL and although it is not enforced in ECO it does help to 
clarify your intentions. It is good practise to precede association names with the self keyword when the association name is 
singular (event) rather than plural (events). 
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Aliases 

Building on the following example of explicitly identifying a token as a member and not a class there is a situation where it is 
not logical to precede the member name with the self keyword. The following OCL expression returns a collection of events 
a Customer has bookings for. 

//Using a customer instance as the root 
self . bookings . event 

In this expression it is clear that the token "event" refers to the association Booking. Event because it is connected directly 
with a period, identifying it as a member; the previous expression would return a collection of Event instances. However, the 
following expression (using a Booking as the root) is not valid and will not evaluate at all. 

self . bookings -> select (event . cancelled) 

This expression will not evaluate because the token "event" is not preceded with a period, identifying it as a member of 
Booking, but unlike in the previous scenario it is not possible to precede "event" with the self keyword because self will 
always refer to the root that the expression is being evaluated against; in this case that would be an instance of Customer, 
and Customer does not have an Event association. 


The solution to this is to use an alias for each booking, so that the "event" token can be replaced with "alias. event" which 
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then clearly identifies it as a member and not a class. Aliases are identified with the | (pipe) symbol and look like this 

//Long format 

self . bookings->select (currentBooking | currentBooking . event . cancelled) 

//Shorter format 

self . bookings->select (b | b . event . cancelled) 


Comparisons 

Comparisons in the OCL are made using a single equals sign. 

self . bookings->select (date = DateTime . today) 


2.7.1 lOcIPsService 


OcIPs is an abbreviation for Object Constraint Language - (evaluated in) Persistent Storage. The lOcIPsService translates 
OCL expressions into the data storage specific query language (usually SQL) in order to perform queries without first having 
to load object contents into the local ECO cache. The lOcIPsService never retrieves any object data, instead it always 
returns a result type of lObjectList, which is a list of "object locators", an object's contents are not loaded until you reference 
the .NET object from the locator, for example 


IOb ject myLocator = { retrieved from somewhere else } ; 

//ECO will ensure the object is loaded if not already 
Console .WriteLine (myLocator . GetValue<Person> ( ) . FirstName ) ; 


This is an important detail because it means that the only information returned from the data storage is a list of object ID's 
rather than the entire contents of the objects. Without this ability evaluating OCL could prove to be very expensive. Take a 
simple harmless looking OCL query such as the following 


2 


Person . alllnstances->select (dateOfBirth = #1978-01-01) 


If this query were to be evaluated in memory ECO would first have to load every instance of the Person class into memory 
and then filter the list down to only those with the specific date of birth. If there were millions of Person objects in the data 
storage this would obviously require a lot of memory and also a lot of network bandwidth. 


1. [DB] Select FirstName, LastName, etc from Person; 

2. [ECO] Receive row data for millions of Person objects 

3. [ECO] Filter the list where the DateOfBirth matches 

4. [App] Receive a collection of object locators that match the criteria 

When this same query is executed with the lOcIPsService the filtering will be performed by the data storage and only the 
ID's of the matching objects will be returned. 


1. [DB] Select FirstName, LastName, etc from Person WHERE DateOfBirth = [format specific to the database}; 

2. [ECO] Receive only the IDs of only the rows that match the critera 

3. [App] Receive a collection of object locators that match the criteria 

Note: The ECO component "OcIPsHandle" uses the lOcIPsService to execute its expression. 
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As you can see there is a big gain from using the lOcIPsService when there is a large number of objects involved such as 
SomeClass . alllnstances where it is anticipated there will be a lot Of object instances (Country . alllnstances would 
be okay, but Person .alllnstances might prove problematic). This also includes "rooted" queries such as 
self .Residents where "self" is in instance of Country, in this case it is anticipated that a country is likely to have many 
residents so you woud really want any ->seiect ( ... J to be performed in the data storage rather than in memory. 


Restrictions of the lOcIPsService 


1 . It does not 
take into 
account 
unsaved 
changes. 

It is important to note that as the filtering is performed by the data storage it is only capable of providing 
a list of objects that have been persisted. If for example you were to modify the DateOfBirth of an 
already persisted Person in your local EcoSpace cache so that it does not match the date #1978-01-01, 
and then not persist those changes, when you execute the OclPs expression 
Person . alllnstances->select (dateOfBirth = #1978-01-01) the result would Still include 
the modified Person. There is a way of ensuring the collection represents both changes that have and 
have not yet been persisted using the in-memory OCL expression AiiLoadedObjects, which will be 
covered in the section lOcIService (0 see page 44). 

2. It can only 
return a 
collection of 
object 
locators. 

The result type is always an IObjectList. This means that it is not possible to end your OCL query with 
operators such as ->size to return the number of items in the list, nor can you for example return a list 
of unique values using ->coiiect (dateOfBirth) . 

3. Is supports 
only a 
subset of 
OCL. 

It is not possible to map all OCL operations to SQL for example. As a consequence not all OCL 
operations are supported. 

4. Derived 
members 
are not 
supported. 

Members in the model marked as derived are calculated in-memory upon request. These values are 
never persisted to the data storage and as a consequence it is not possible to use them in OCL 
expressions evaluated by this service. 


Executing queries 

This service has a number of overloaded methods for evaluating OCL expressions, each of which is named Execute () . 
The most simple overload accepts only an OCL expression to evaluate. 


IObjectList locators; 

string query = "Person . alllnstances->select (dateOfBirth = #1978-01-01)"; 
locators = EcoSpace . OclPs . Execute (query ) ; 


The above example selects the object locators only for the Person objects that were born on January the 1st, 1978. Note 
that no Person data is returned from this query. Any time you access locator .AsObject or locator . Getvalue<T> the 
individual object will be loaded. To retrieve multiple objects in as few DB trips as possible you can either use the 
GetAsiLlst<T> () method on the result or use the EnsureRange () method on the IPersistenceService (0 see page 133) 
to pre-load. Note that evaluating an in-memory query against the result using the lOcIService will also fetch object data into 
the local EcoSpace cache. The following example not only identifies which Person objects match the criteria but also loads 
the objects' contents into the cache. 


IList<Person> people; 

string query = "Person . alllnstances->select (dateOfBirth = #1978-01-01)"; 
people = EcoSpace . OclPs . Execute (query) . GetAsIList<Person> ( ) ; 
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The next overload is similar to the first except that it additionally takes two integer parameters. 


Name 

Type 

Purpose 

maxAnswers 

Int32 

Limits the number of object locators returned. 

offset 

Int32 

Zero based index of the first object in the list to return. 


This overload is useful for either data paging (in which case you should have an ->orderBy ( . . . ) operation in your OCL 
expression to ensure a consistent order) or simply to reduce the number of objects returned on a search screen for example. 


int raaxAnswers = 50; 

IList<Person> people; 

string query = "Person . alllnstances->select (dateOfBirth = #1978-01-01)"; 
people = EcoSpace . OclPs . Execute (query , maxAnswers, 0 ) . GetAsIList<Person> ( ) ; 


The next overload expects not only an OCL expression to evaluate but also a root context to evaluate it against. The root is 
an lElement, which means that the context could be either a single instance of a modeled business class or a collection of 
instances. The root provided is always referenced as the OCL keyword self in expressions. Note that although lElement 
can be used to represent other values such as strings, integers, and dates it is not possible to use these as a root context for 
evaluating an OclPs expression. 


City city = { retrieved from somewhere else } ; 

IList<Person> people; 

string query = "self . residents->select (dateOfBirth = #1978-01-01)"; 

people = EcoSpace . OclPs . Execute (city . AsIObject () , query ). GetAsIList<Person> () ; 

/* 

Equivalent to SQL 

select FirstName, LastName, etc from Person 

where City = 132232 and DateOfBirth = { DB specific date format}; 

*/ 
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It is not mandatory to use the root context as the root of the OCL evaluation. The following example produces the same 
result as the previous example despite starting the OCL expression with Person . aiiinstances. 


City city = { retrieved from somewhere else } ; 

IList<Person> people; 

string query = "Person . alllnstances->select (city = self ) ->select (dateOfBirth = 
#1978-01-01)"; 

people = EcoSpace . OclPs . Execute (city . AsIObject () , query ) . GetAsIList<Person> ( ) ; 


The final overload accepts a number of additional parameters. 


Name 

Type 

Purpose 

root 

lElement 

Acts as a context for the keyword self in OCL expressions. This parameter may be 
null. 

variableList 

lExternalVariableList 

This parameter provides a variable list which is used when parsing the OCL 
expression. Any unidentified part of the expression that looks like it should be a literal 
value is checked against this variable list to see if it is a named value. This parameter 
may be null. 

expression 

String 

The OCL expression to evaluate. 

maxAnswers 

Int32 

The total number of answers to return. 


27 






2.7 Query services 


ECO Services 


lOcIPsService 


[offset Int32 The zero based index of the first result to return. 

The IVariableFactoryService (0 see page 1 8) section of this document provides an example for the use of this overload. 


2.7.1. 1 OCL operations supported by lOcIPsService 

2.7.1. 1.1 + 


Source 

Int32 

Parameters 

Int32 value 

Result 

Int32 


Description 

Returns the result of adding the specified value to the source. 


2 


Example 

1 + 2 


Notes 

Additional overloads exist for Int64 and Double. 


2.7.1. 1.2- 


Source 

Int32 

Parameters 

Int32 value 

Result 

Int32 


Description 

Returns the result of subtracting the specified value from the source. 


Example 

3-2 


Notes 

Additional overloads exist for Int64 and Double. 
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2 . 7 . 1 . 1 . 3 * 


Source 

Int32 

Parameters 

Int32 factor 

Result 

Int32 


Description 

Returns the result of multiplying the source by the factor. 


Example 

5*5 


Notes 

Additional overloads exist for Int64 and Double. 


2 . 7 . 1 . 1 . 4 / 


Source 

Int32 

Parameters 

Int32 divisor 

Result 

Int32 


2 


Description 

Returns the result of dividing the source by the divisor. 


Example 

10/2 


Notes 

Additional overloads exist for Int64 and Double. 


2 . 7 . 1 . 1. 5 < 


Source 

A 

> 

< 

V 

Parameters 

<Any> value 

Result 

Boolean 
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Description 

Returns true if the source is less than the parameter. 


Example 

6 < 12 


2 . 7 . 1 . 1.6 <= 


Source 

A 

> 

< 

V 

Parameters 

<Any> value 

Result 

Boolean 


Description 

Returns true if the source is less than or equal to the parameter. 


Example 

6 <= 12 


2 . 7 . 1 . 1.7 <> 


Source 

A 

> 

*< 

V 

Parameters 

<Any> value 

Result 

Boolean 
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Description 

Returns true if the source is not equal to the parameter. 


Example 

6 <> 12 


2 . 7 . 1 . 1.8 = 


Source 

A 

> 

< 

V 

Parameters 

<Any> value 

Result 

Boolean 


Description 

Returns true if the source is equal to the parameter. 
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Example 

1 = 1 


2.7.1. 1. 9 > 


Source 

A 

> 

< 

V 

Parameters 

<Any> value 

Result 

Boolean 


Description 

Returns true if the source is greater than the parameter. 


Example 

12 > 6 


2.7.1.1.10 >= 


Source 

A 

> 

< 

V 

Parameters 

<Any> value 

Result 

Boolean 
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Description 

Returns true if the source is greater than or equal to the parameter. 


Example 

12 >= 6 


2.7.1.1.11 Allinstances 


Source 

<Type> 

Parameters 


Result 

Collection(<lnstance>) 


Description 

Returns all instances of the source type. The type can be a business class such as Person. In OCL and EAL the type can 
also be an enumeration type used in the model such as Gender or OrderState 
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Example 

Person . alllnstances 


2.7.1.1.12 Average 


Source 

Collection(Decimal) 

Parameters 


Result 

Decimal 


Description 

Returns the average of a collection of numerical values. 


Example 

Person . alllnstances . age->average 


Notes 

Additional overloads exist for Int32, Int64, and Double; each of which return Double and not Decimal. 


2.7.1.1.13 Difference 


Source 

Collection(<Any>) 

Parameters 

Collection(<Any>) value 

Result 

Collection(<Any>) 
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Description 

Returns a copy of the source collection minus all elements in the parameter. 


Example 

var_Personl . f riends->dif ference (var_Person2 . friends) 


Notes 

To remove a single element see Excluding. 


2.7.1.1.14 Div 


Source 

Int32 

Parameters 

Int32 divisor 

Result 

Int32 
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Description 

Returns the result of dividing the source by the divisor. 


Example 

10 div 2 


2.7.1.1.15 Exists 


Source 

Collection(<Any>) 

Parameters 

Boolean expression 

Result 

Boolean 


Description 

Returns true if the parameter results in true for any of the items in the collection. 


Example 

self . f riends->exists ( f I f. Gender = Gender :: Male ) 


Notes 

The syntax within the brackets is similar to a lambda expression, where each item in the Collection(Person) is assigned the 
alias "f" for the rest of the expression. 
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2.7.1.1.16 ForAII 


Source 

Collection(<Any>) 

Parameters 

Boolean expression 

Result 

Boolean 


Description 

Returns true if the parameter results in true for every item in the collection. 


Example 

self . f riends->f orAll ( f | f. Gender = Gender :: Male ) 

The person in question only has male friends. 
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2.7.1.1.17 Implies 


Source 

Boolean 

Parameters 

Boolean comparison 

Result 

Boolean 


Description 

The following table shows possible permutations and the result. 


Source 

Parameter 

Result 

False 

False 

True 

False 

True 

True 

True 

False 

False 

True 

True 

True 
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Example 

If a Weather class has two boolean attributes "Raining" and "Cloudy" the following constraint would ensure that it must be 
cloudy in order for it to be raining. 


raining implies cloudy 


Includes 


Source 

Collection(<Any>) 

Parameters 

<Any> value 

Result 

Boolean 


Description 

Returns true if the parameter exist in the source. 


Example 

self . friends-> includes (self. Fat her) 

The person in question is friends with his/her father. 


2.7.1.1.19 Intersection 


Source 

Collection(<Any>) 

Parameters 

Collection(<Any>) value 

Result 

Collection(<Any>) 


34 


















2.7 Query services 


ECO Services 


IQcIPsService 


Description 

Returns a collection of all elements in the source that are also in the parameter. 


Example 

self . debt or s-> inter sect ion (self. creditors) 

Returns a collection of people who are both debtors and creditors. 


2.7.1.1.20 IsEmpty 


Source 

Collection(<Any>) 

Parameters 


Result 

Boolean 


Description 

Returns true if a collection has no elements in it. 


Example 

self . debtors->isEmpty 

Returns True if the person has no debtors. 


2 


Notes 

IsEmpty may also be used on an association to a single object to check if it has a value. It is recommended that IsEmpty is 
used in such a case rather than comparing the associated object with nil. 

self . linkToSingleOb ject = nil [Incorrect] 
self . linkToSingleOb ject->isEmpty [Correct] 


2.7.1.1.21 IsNull 


Source 

A 

> 

< 

V 

Parameters 


Result 

Boolean 


Description 

Returns true if the source is null. 


Example 

self . f irstName . isNull 


35 













2.7 Query services 


ECO Services 


IQcIPsService 


Notes 

To check an association to a single object use isEmpty. 


2.7.1.1.22 Length 


Source 

String 

Parameters 


Result 

Int32 


Description 

Returns the length of a string. 


Example 

Person . alllnstances->select ( firstName . length < 2) 


2.7.1.1.23 MaxValue 


Source 

Collection(lnt32) 

Parameters 


Result 

Int32 
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Description 

Returns the largest value found in the source collection. 


Example 

Person . alllnstances->select (height = Person . alllnstances . height->maxValue) 

Selects all of the tallest people. 


Notes 

Additional overloads exist for Int64, Double, and Decimal. 


2.7.1.1.24 MinValue 


Source 

Collection(lnt32) 

Parameters 


Result 

Int32 
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Description 

Returns the minimum value found in the source. 


Example 

Person . alllnstances->select (height = Person . alllnstances . height->minValue) 

Selects all of the shortest people. 


Notes 

Additional overloads exist for Int64, Double, and Decimal. 


2.7.1.1.25 Mod 


Source 

Int32 

Parameters 

Int32 modulo 

Result 

Int32 


Description 

Returns the result of performing a modulus on the source using the modulo. 


Example 

17 mod 10 

Returns 7. 


2.7.1.1.26 Not 


Source 

Boolean 

Parameters 


Result 

Boolean 


Description 

Returns the result of performing a logical NOT operation on the source. 


Example 

User . alllnstances->select (not suspended) 
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2.7.1.1.27 NotEmpty 


Source 

Collection(<Any>) 

Parameters 


Result 

Boolean 


Description 

Returns true if a collection has at least one element in it. 


Example 

self . debtors->notEmpty 

Returns True if the person has debtors. 
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NotEmpty may also be used on an association to a single object to check if it has a value. It is recommended that NotEmpty 
is used in such a case rather than comparing the associated object with nil. 

self . linkToSingleOb ject <> nil [Incorrect] 
self . linkToSingleOb ject ->not Empty [Correct ] 


2.7.1.1.28 OrderBy 


Source 

Collection(<Any>) 

Parameters 

<Any> expression 

Result 

Collection(<Any>) 


Description 

Returns a collection based on the source which has been ordered into ascending order based on the value in the parameter. 


Example 

self . debtors->orderBy (oldestUnpaidDebt ) 

Returns all debtors in order of the debtor with the oldest unpaid debt first. 

self . debtors->orderBy (lastName, firstName) 

Returns all debtors ordered by their last name, for debtors with the same last name, the first name is used as a secondary 
key 


Notes 

Using OrderBy it is possible to order by multiple keys, but only in ascending order. To order by multiple items in different 
directions, use OrderGeneric. 
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2.7.1.1.29 OrderDescending 


Source 

Collection(<Any>) 

Parameters 

<Any> expression 

Result 

Collection(<Any>) 


Description 

Returns a collection based on the source which has been ordered into descending order based on the value in the 
parameter. 

Example 

self . debtors->orderDescending (amountOwed) 

Returns all debtors in order of the debtor with the greatest amount of debt first. 
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Notes 

Using OrderDescending it is possible to order by multiple keys, but only in ascending order. To order by multiple items in 
different directions, use OrderGeneric. 


2.7.1.1.30 OrderGeneric 


Source 

Collection(<Any>) 

Parameters 

<Any> expression 
SortDirection direction 

Result 

Collection(<Any>) 


Description 

Returns a collection based on the source which has been ordered as specified by the parameters. OrderGeneric takes a 
minimum of two parameters; the first identifies the sort expression, and the second identifies the sort direction (ascending or 
descending). These two parameters may be repeated multiple times in order to provide sorting by multiple items. 


Example 

self . debtors->orderGeneric (oldestUnpaidDebt , OclSortDirection : :ascending, amountOwed, 
OclSortDirection : :descending) 

Returns all debtors primarily in order of the debtor with the oldest unpaid debt first, and then secondarily by the debtor 
owning the highest amount of money. 


OldestUnpaidDebt 

AmountOwed 

2008-01-01 

1000.00 

2008-01-01 

800.00 

2008-01-01 

700.00 
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2008-02-01 

1000.00 

2008-02-01 

550.00 


2.7.1.1.31 Reject 


Source 

Collection(<Any>) 

Parameters 

Boolean expression 

Result 

Collection(<Any>) 


Description 

Returns a collection based on the source excluding any elements where the boolean expression evaluated to True. 


Example 

self . friends->re ject (age < 18 ) 

This is functionally equivalent to the following 

self . f riends->select (age >= 18 ) 


2.7.1.1.32 Select 


Source 

Collection(<Any>) 

Parameters 

Boolean expression 

Result 

Collection(<Any>) 
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Description 

Returns a collection based on the source including only elements where the boolean expression evaluated to True. 


Example 



User . alllnstances->select (u 

u.firstName = 

' Peter ') ->select (u 

u.lastName = 'Morris') 

Returns all users with the name "Peter Morris". 



this is equivalent to 





User . alllnstances->select (u 

(u . f irstName = 

'Peter') and (u.lastName = 'Morris')) 


2.7.1.1.33 Size 


Source 

Collection(<Any>) 

Parameters 


Result 

Int32 
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Description 

Returns the size of a collection. 


Example 

Person . alllnstances->select (p | p . f riends->size >= 5) 

Returns all people with 5 or more friends. 


2.7.1.1.34 SqILike 


Source 

String 

Parameters 

String pattern 

Result 

Boolean 


Description 

Returns True if the source matches the pattern specified in the parameter. This is similar to the LIKE statement in SQL. 


Example 

Person . alllnstances->select (p | p . lastName . sqlLike (' %orris ') ) 

Returns a collection of people who have a last name ending with "orris". 
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Notes 

When evaluated in memory, this operation is case sensitive, but some databases treats the LIKE operator as a 
caseinsensitive operator. For guaranteed case insensitivity, use sqILikeCaselnsensitive 


% is used to denote a match with zero or more unknown letters 
_ is used to denote a match with exactly one unknown letter. 


Value 

Match 

Morris 

True 

Norris 

True 

Orris 

False 


2.7.1 .1 .35 SqILikeCaselnsensitive 


Source 

String 

Parameters 

String pattern 

Result 

Boolean 
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Description 

Returns True if the source matches the pattern specified in the parameter. This is similar to the LIKE statement in SQL but 
case insensitive. 


Example 

Person. alllnstances->select (lastName . sqlLikeCase Insensitive ( ' %orris ' ) ) 

Returns a collection of people who have a last name ending with "orris", regardless of case. 


Notes 

Unlike the SqILike operation the comparison is case insensitive. 


Value 

Match 

Morris 

True 

Norris 

True 

Orris 

True 


2.7.1.1.36 Sum 


Source 

Collection(lnt32) 

Parameters 


Result 

Int32 


Description 

Returns the sum of the values in the collection 


Example 

Person . alllnstances->select (debts ,value->sum > 10000) 

Selects all people who have a debt of at least 10,000. 


Notes 

Additional overloads exist for Int64, Double, and Decimal. 


2.7.1.1.37 ToLower (String) 


Source 

String 

Parameters 


Result 

String 
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Description 

Converts a string value to lower case. 


Example 

Person . alllnstances->select ( firstName . toLower = 'peter') 

Returns people with the first name "Peter", "pETeR" or any other case-variation of "peter". 


Notes 

When selecting you may wish to use SqILikeCaselnsensitive as it permits the use of wildcards. The ToLower operation is 
mostly used for presenting data in a user interface in a specific format. 


2.7.1.1.38 Tol)pper(String) 


Source 

String 

Parameters 


Result 

String 


Description 

Converts a string value to upper case. 


Example 

Person . alllnstances->select ( firstName . toLower = 'PETER') 

Returns people with the first name "Peter". 


Notes 

When selecting you may wish to use SqILikeCaselnsensitive as it permits the use of wildcards. The ToUpper operation is 
mostly used for presenting data in a user interface in a specific format. 

2.7.1.1.39 Union 


Source 

Collection(<Any>) 

Parameters 

Collection(<Any>) value 

Result 

Collection(<Any>) 


Description 

Returns a collection of all elements in the source combined with all elements in the parameter. 
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Example 

self . debtors->union (self. creditors) 

Returns a collection of people who are either a debtors or creditors of a person. 


2.7.2 IQcIService 


Ocl is an abbreviation for Object Constraint Language. The lOcIService evaluates OCL expressions in memory. Objects are 
fetched from the data storage automatically if they are required in order to evaluate the expression passed, the following 
expression evaluated against a PurchaseOrder would automatically load all PurchaseOrderLine objects related to the order 
if they were not already loaded into the local EcoSpace cache. 


self. lines. value -> sum 


Due to the fact that the lOcIService evaluates in memory it is advisable that you do not evaluate expressions such as 
class . aiiinstances unless you are certain that there will be an acceptable number of instances. For example evaluating 
Country . aiiinstances would be acceptable whereas evaluating an expression such as 
stockMovement . aiiinstances would most likely be unacceptable due to the fact that you cannot guarantee that over 
time there will not be millions of StockMovement objects. 


It is important to note that even OCL expressions which return a small number of results may still load a large number of 
objects into the local EcoSpace cache. 
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StockMovement . alllnstances->select (id = 123456789) 


1. [DB] Select {names of columns} from StockMovement 

2. [ECO] Receive row data for millions of StockMovement objects 

3. [ECO] Store the data in the local EcoSpace cache 

4. [ECO] Filter the list where the id matches 

5. [App] Receive a collection of object locators that match the criteria, in this case a single object out of over 100 million 
objects 

When such an expression is required it is advisable to use the lOcIPsService (0 see page 25) instead. 


Evaluating OCL expressions 

This service has a number of overloaded methods for evaluating OCL expressions, each of which is named Evaluate () . 
The most simple overload accepts only an OCL expression to evaluate. 


EcoSpace . Ocl . Evaluate (" 1 + 2"); 


The next overload accepts an additional parameter identifying a context for the evaluation. 
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Name 

Type 

Purpose 

root 

IElement 

Identifies an element to be used as the context for the evaluation and also to determine the value to use 
wherever the evaluator encounters the keyword self in the expression. 

For in-memory evaluations the context may be any kind of IElement 

• Value types such as Int32, String, etc 

• Instances of modeled classes (as per the following example) 

• A collection of IElement such as a list of instances or a list of values 


Person personl = new Person (EcoSpace) ; 
personl . DateOfBirth = DateTime . Today; 

EcoSpace . Ocl . Evaluate (personl . AsIObject () , "age + 1") 


The next overload accepts provides a way of identifying multiple values as parameters 


Name 

Type 

Purpose 

root 

IElement 

Identifies an element to be used as the context for the evaluation. 

expression 

String 

The OCL expression to evaluate. 

variableList 

lExternalVariableList 

A collection of variables to use when parsing the OCL expression. 


Person personl = new Person (EcoSpace) ; 
personl . DateOfBirth = DateTime . Today; 

IModif iableVariableList vars = EcoSpace . VariableFactory . CreateVariableList () ; 
vars . AddConstant ( " var_Year s " , 2 ) ; 

EcoSpace . Ocl . Evaluate (personl . AsIObject () , "age + var_Years", vars) ; 


Note: There is an additional overload which is the same as this except it does not have the initial root parameter. 


Evaluating and subscribing 

The lOcIService has a number of overloaded methods named EvaluateAndSubscribe () . These methods are essentially 
the same as the Evaluate methods except that they additionally take two parameters of the type iSubscriber. The 
subscription mechanism is covered in more detail in the subscriptions (a see page 144) section of this document so will not 
be covered in great depth here. The only method that involves subscriptions which will be covered here is the 

GetDerivedElement () method. 


As ECO parses an OCL expression to evaluate it it accesses various element values held within the local cache, elements 
such as object instances, attributes, and roles are known as domain elements because they are physical parts of the 
modeled domain (Person, Person. FirstName, Person. LastName, etc). When an OCL expression returns a domain element 
you can be sure that whenever the value of the element changes your result will also change, for example: 


Person personl = new Person (EcoSpace ) ; 
personl . FirstName = "Fred"; 

string ocl = "firstName"; 

IElement resultElement = EcoSpace . Ocl . Evaluate (personl . AsIObject () , ocl); 
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personl . FirstName = "Peter"; 

MessageBox . Show ( " resultElement value = " + resultElement . GetValue<string> ( ) ) ; 


At the point the evaluation is performed the person's first name is "Fred", the element returned by the evaluation is stored in 
the local variable resultElement. The person's first name is then changed to "Peter" and a message box is then used to 
show the value held by the element returned earlier. 



Here you see that the message box shows the new value "Peter" and not the initial value "Fred". This is because the result 
of the evaluation was a domain element, meaning that the expression identified a member of a class rather than merely a 
calculated value. To clarify this take a look at the following example 


Person personl = new Person (EcoSpace) ; 
personl . FirstName = "Fred"; 
personl . LastName = "Morris"; 

string ocl = "firstName + ' ' + lastName"; 

IElement resultElement = EcoSpace . Ocl . Evaluate (personl . AsIObject () , ocl); 
personl . FirstName = "Peter"; 

MessageBox . Show (" resultElement value = " + resultElement . GetValue<string> ()) ; 
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Here you see that the message box now shows the result as it would have been at the time of evaluation rather than 
reflecting any changes made since. This is because the result is evaluated as the values of two domain elements combined 
together with a single space between them, the result itself is not a domain element but a new element constructed solely for 
the purpose of holding the result. If you require the value of your element to change to reflect modifications after it was 
evaluated you can use the GetDerivedEiement () method. 


Person personl = new Person (EcoSpace) ; 
personl . FirstName = "Fred"; 
personl . LastName = "Morris"; 

string ocl = "firstName + ' ' + lastName"; 

IElement resultElement = EcoSpace . Ocl . Evaluate (personl . AsIObject () , ocl); 

IElement derivedElement = EcoSpace .Ocl . GetDerivedEiement (personl .AsIObject () , ocl); 

personl . FirstName = "Peter"; 

MessageBox . Show (" resultElement value = " + resultElement . GetValue<string> ()) ; 
MessageBox . Show ( "DerivedElement value = " + derivedElement . GetValue<string> ()) ; 


46 






2.7 Query services 


ECO Services 


IQcIService 




Here you can see that the derived element's value changes as the values it is derived from change. Subscriptions (a see 
page 144) are covered in another part of this document. 


Combining evaluations 

It is sometimes necessary to evaluate expressions in memory due to one or more of the following reasons: 

1. You need to select on a derived (calculated) member or the result of a method, and the lOcIPsService does not support 
this functionality. 

2. You need to include new and/or modified object instances in the local EcoSpace cache that also meet this criteria. 

The following OCL example illustrates this point. 


Person 

attributes 

♦ DateOfBirth: DateTime 
+ FirstName: string 

♦ LastName: string 

operations 
+ GetAge: int 


2 


GetAge () is defined as a method with lsQuery=True. This is a useful trick for when you want to create a calculated member 
in code but not all of the elements involved in calculating its result are capable of notifying subscribers when they change - in 
this example there is no way to subscribe to DateTime. Today using an ECO ISubscriber so a method is created instead with 
IsQuery set to True so that the IQcIService knows it may execute the query without causing any side affects. 


public int GetAge ( ) 

{ 

DateTime today = DateTime . Today ; 
int result = today. Year - DateOfBirth . Year ; 
if (today . DayOf Year < DateOfBirth . DayOf Year ) 
result — ; 
return result; 

} 


Now consider the following OCL expression: 


Person . alllnstances->select (firstName . sqlLikeCaselnsensitive ( ' Pete% ' ) ) ->select (GetAge ( ) 
>= 18 ) 


It is not possible to evaluate this expression using the lOcIPsService because part of the expression refers to the method 
GetAge (). It is also not recommended that this expression is evaluated using the lOcIService as this would load all 
instances of the Person class into memory in order to evaluate the rest of the expression, and this could be very detrimental 
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to system performance if there are many object instances. The solution to this is to perform two expression evaluations, one 
against each of the two services. 


string psCriteria = 

"Person . alllnstances " + 

"->select (firstName . sqlLikeCaselnsensitive ( ' Pete% ' ) ) " ; 
IObjectList people = EcoSpace . OclPs . Execute (psCriteria) ; 

string memoryCriteria = " self->select (GetAge ( ) >= 18)"; 
people = EcoSpace . Ocl . Evaluate (people, memoryCriteria); 

IList<Person> result = people . GetAsIList<Person> () ; 


The above code example first executes part of the expression as SQL and loads into memory only a collection of object 
locators, one for each object in the data storage that matched the criteria 
firstName . sqlLikeCaselnsensitive ( 'Pete% ’) . The list of object locators is then used as the context for an 
in-memory evaluation to filter the collection down to only people who are at least 18 years old at the time of evaluating the 
expression. The problem with this example is that only objects identified as a match by the database will be considered for 
inclusion by the lOcIService, this is because we are providing a specific list of object locators and then starting the 
expression with the self keyword. If there are instances of the Person class in the local cache which have not yet been 
saved then the data base has no way of knowing about this instance and including its object locator in the initial result; 
likewise if a previously saved object has been modified and the changes not yet saved the final result will not include objects 
which should be there. 


One useful side affect of using the lOcIPsService to retrieve a list of object locators is that these objects are then considered 
to be "loaded" even though we only have an object locator (identity of the object) and not the actual data for those objects. 
This is useful because there is an OCL operation available in the lOcIService named AiiLoadedObjects which can be 
used to evaluate expressions only against objects that have already had their identity loaded into the cache. 


2 


//Execute the query to load object locators into memory 
string psCriteria = 

"Person . alllnstances " + 

"->select (firstName . sqlLikeCaselnsensitive ( ' Pete% ' ) ) " ; 
EcoSpace .OclPs . Execute (psCriteria) ; 

//Now evaluate only on objects already loaded 
string memoryCriteria = 

"Person.allLoadedObjects" + 

"->select (firstName . sqlLikeCaselnsensitive ( ' Pete% ' ) ) " + 
"->select (GetAge ( ) >= 18)"; 

IElement people = EcoSpace . Ocl . Evaluate (memoryCriteria) ; 
IList<Person> result = people . GetAsIList<Person> () ; 


This is exactly the kind of approach you will see on the EcoDataSource component when creating ECO powered web 
applications, where it is possible to specify both a PsExpression property for evaluating the query as SQL on the database 
and also an Expression property which is evaluated against the result of the PsExpression. 


2.7.2. 1 OCL operations supported by lOcIService 

The lOcIService supports all of the lOcIPsService operations (0 see page 28) plus the following additional operations. 
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2 . 7 . 2 . 1.1 - 


Source 

DateTime 

Parameters 

TimeSpan value 

Result 

DateTime 


Description 

Returns the source DateTime with the specified TimeSpan parameter subtracted from it. 


Example 

self . dateOfBirth - #00:01 


Source 

DateTime 

Parameters 

DateTime 

Result 

TimeSpan 


Description 

Subtracts the DateTime parameter from the source and returns a TimeSpan. 


Example 

dateReturned - dateHired 


Source 

TimeSpan 

Parameters 

TimeSpan 

Result 

TimeSpan 


Description 

Subtracts the parameter from the source and returns a TimeSpan. 


Example 

endTime - startTime 
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2.7.2.1.2 + 


Source 

DateTime 

Parameters 

TimeSpan value 

Result 

DateTime 


Description 

Returns the source DateTime with the specified TimeSpan parameter added to it. 


Example 

self . dateOfBirth + #08:30 


Source 

TimeSpan 

Parameters 

TimeSpan 

Result 

TimeSpan 


Description 

Returns the source TimeSpan with the specified TimeSpan parameter added to it. 


Example 

endTime > (startTime + #01:00) 


2.7.2.1.3 AlllnstancesAtTime 


Source 

<Type> 

Parameters 

Int32 versionNumber 

Result 

Collection(<lnstance>) 


Description 

Returns all instances of the source type for the given version number. See the IVersionService (0 see page 141) for more 
details. 


Example 

Person . all Inst ancesAt Time (0) 


Returns a historical view of all Person instances that existed after the first ever call to UpdateDatabase. 
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2.7.2.1.4 AIILoadedObjects 


Source 

<Type> 

Parameters 


Result 

Collection(<lnstance>) 


Description 

Returns all instances of the source type that have already been loaded into the local cache. This list will also include objects 
that have had their unique ID (object locator) loaded but not yet had their data contents loaded. No additional object locators 
will be retrieved from the data storage, however, accessing a member value via code or OCL will ensure that the instance's 
member data is in the cache. 


Example 

Person . allLoadedOb jects 


2 


Returns all instances of Person that have already been loaded. 


2.7.2.1.5 AllSubClasses 


Source 

<Type> 

Parameters 


Result 

Collection(String) 


Description 

Returns the names of all classes descended from the source type. 


Example 

Person . allSubClasses 


2.7.2.1.6 AllSuperClasses 


Source 

<Type> 

Parameters 


Result 

Collection(String) 


Description 

Returns the names of all classes the source type descends from. 
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Example 

Person . allSuperClasses 


2.7.2.1.7 AssociationEnds 


Source 

<Type> 

Parameters 


Result 

Collection(String) 


Description 

Returns the names of all properties of the class that are association ends to another modeled class. This list includes both 
navigable and non-navigable association ends, and also includes association ends inherited from all super classes. 


Example 

Person . associationEnds 


2.7.2.1.8 AsString 


Source 

<Any> 

Parameters 


Result 

String 


2 


Description 

Represents the source as a string. When the source is an instance of a class it will evaluate the Default String 
Representation expression of the class. 


Example 

self . dateOfBirth . asString 


2.7.2.1.9 At 


Source 

Collection(<Any>) 

Parameters 

Int32 index 

Result 

<Any> 


Description 

Returns the item within the collection at the specified index. The lower bound of the index is 1 . 
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Example 

Person . alllnstances->at (1) 


Notes 

To specify a zero based index use ->atO 


2.7.2.1.10 AtTime 


Source 

<Object> 

Parameters 

Int32 versionNumber 

Result 

<Object> 


Description 

Returns a historical view of the source object at the point in time identified by the version number. See the IVersionService 
(a see page 141) for more details. 


Example 

self . atTime (0) 


2 


Returns a historical view of the source object that existed after the first ever call to UpdateDatabase. 


2.7.2.1.11 Attributes 


Source 

<Type> 

Parameters 


Result 

Collection(String) 


Description 

Returns a collection of strings, each one being the name of a modeled property (UML attribute) on the specified class type. 
The list will contain attributes modeled on the current class plus any inherited from its base class; the list will not include any 
association ends. 


Example 

IElement attributes; 

attributes = EcoSpace . Ocl . Evaluate ( "Class_l . attributes ") ; 
foreach (string current in attributes . GetAsIList<string> () ) 
MessageBox . Show (current) ; 


2.7.2.1.12 Collection operations 
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2.7.2.1.12.1 Append 


Source 

Collection(<Any>) 

Parameters 

<Any> value 

Result 

Collection(<Any>) 


Description 

Returns the source collection with the parameter added to it. 


Example 

var_customerl . orders->append (var_customer2 . orders ) 


Returns a collection of orders from customerl with a single order from customer2 appended to the end of the list. 


2.7.2.1.12.2 AsBag 


Source 

Collection(<Any>) 

Parameters 


Result 

Collection(<Any>) 


Description 

Evaluates the source and returns a collection based upon it that is capable of holding duplicate entries. By default 
associations are Sets, meaning that they do not allow duplicate values. This operation does not alter the source collection, it 
merely changes the context. 


2 


Example 

//Products will only appear once 

var_order 1 . lines . product->including (var_order2 . lines . product ) 

//Duplicate products may appear 

var_order 1 .lines . product ->asBag-> including ( var_order2 .lines . product ) 

This operation is not very useful in ECO. It is implemented as a part of complying with the OCL specification. In ECO, all 
object lists have an explicit order order. 


2.7.2.1.12.3 AsCommaList 


Source 

Collection(String) 

Parameters 


Result 

String 


Description 

Takes a collection of strings as a source and returns a single string containing each of the values in the collection separated 
by commas. 


54 












2.7 Query services 


ECO Services 


IQcIService 


Example 

City city = new City (EcoSpace) ; 

Person personl = new Person (EcoSpace) ; 
personl.City = city; 
personl . FirstName = "Peter"; 

Person person2 = new Person (EcoSpace ) ; 
person2.City = city; 
person2 . FirstName = "Fred"; 

string ocl = " self . people . f irstName->asCommaList " ; 
string result = 

EcoSpace . Ocl . Evaluate (city . AsIOb ject ( ) , ocl). GetValue<string> ( ) ; 
MessageBox . Show (result ) ; 


Returns the value 

Peter, Fred 


2.7.2.1.12.4 AsSeparatedList 


Source 

Collection(String) 

Parameters 

String separator 

Result 

String 


2 


Description 

Takes a collection of strings as a source and returns a single string containing each of the values in the collection separated 
by the specified separator. 


Example 

City city = new City (EcoSpace) ; 

Person personl = new Person (EcoSpace) ; 
personl.City = city; 
personl . FirstName = "Peter"; 

Person person2 = new Person (EcoSpace ) ; 
person2.City = city; 
person2 . FirstName = "Fred"; 

string ocl = " self . people . f irstName->asSeparatedList ( 1 + ')" ; 
string result = 

EcoSpace . Ocl . Evaluate (city .AsIOb ject () , ocl). GetValue<string> ( ) ; 
MessageBox . Show (result ) ; 


Returns the value 

Peter+Fred 
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2.7.2.1.12.5 AsSequence 


Source 

Collection(<Any>) 

Parameters 


Result 

Collection(<Any>) 


Description 

Evaluates the source and returns a copy of the that permits manual reordering. Reordering the resulting element does not 
affect the source. 


2.7.2.1.12.6 AsSet 


Source 

Collection(<Any>) 

Parameters 


Result 

Collection(<Any>) 


2 


Description 

Returns a collection based on the source with all duplicates removed. 

Example 

self . orders . lines . product->asSet 


Returns a distinct list of products sold to a specific customer. 


Example 

Person personl = new Person (EcoSpace) ; 
personl . FirstName = "Peter"; 

Person person2 = new Person (EcoSpace) ; 
person2 . FirstName = "Fred"; 

IObjectList originalPeople = 

EcoSpace . VariableFactory . CreateTypedOb jectList (typeof (Person) , true) ; 
originalPeople .Add (personl . As I Ob ject ( ) ) ; 
originalPeople .Add (personl . AsIOb ject ( ) ) ; 
originalPeople .Add (person2 .AsIOb ject ( ) ) ; 
originalPeople .Add (person2 .AsIOb ject ( ) ) ; 


string ocl = " self->asSet " ; 

IElement result = 

EcoSpace . Ocl . Evaluate (originalPeople, ocl); 
IList<Person> people = result . GetAsIList<Person> () ; 
foreach (Person person in people) 

MessageBox . Show (person . FirstName ) ; 

Will show only two message boxes. 
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2.7.2.1.12.7 Collect 


Source 

Collection(<Any>) 

Parameters 

expression 

Result 

Collection(<Any>) 


Description 

A new collection is created, and for each element in the source the parameter is added. 


Example 


private void TestCollect ( ) 

{ 

CreateOrder (1) ; 

CreateOrder (2) ; 

CreateOrder (3) ; 

IElement result; 

result = EcoSpace . Ocl . Evaluate ( "Order . allInstances->collect (o 
o . orderLines->size) ") ; 

foreach (int value in result . GetAsIList<int> () ) 

MessageBox . Show (value . ToString ( ) ) ; 

} 

private void CreateOrder (int count) 

{ 

Order order = new Order (EcoSpace ) ; 
for (int i = 0; i < count; i++) 

{ 

OrderLine line = new OrderLine (EcoSpace) ; 
line. Order = order; 



If multiple arguments are specified in the collect-operation, the result will be a collection of tuples: 

Person . allInstances->collect (firstName, lastName) 

Will return a collection of tuples of pairs of strings 

Person . allInstances->collect ( firstName, lastName, friends->select (friends->size > 5)) 

Will return a collection of tuples that contains the firstname, lastname and a list of friends with more than 5 friends. 
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2.7.2.1.12.8 Count 


Source 

Collection(<Any>) 

Parameters 

<Any> 

Result 

Int32 


Description 

Returns the number of occurances of the parameter in within the source collection. 

self. friends. f riends->count (self) 

calculates how many of a persons friends who have the person listed as a friend. 
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2.7.2.1.12.9 Excluding 


Source 

Collection(<Any>) 

Parameters 

<Any> value 

Result 

Collection(<Any>) 


Description 

Returns a copy of the source minus the value specified in the parameter. 


Example 

Person . alllnstances->excluding (self) 


2.7.2.1.12.10 FilterOnType 


Source 

Collection(<Object>) 

Parameters 

Type requiredType 

Result 

Collection(<Object>) 


Description 

Returns a copy of the source; excluding any elements that are not of the type specified and not descended from the type 
specified. 


Example 



Returns all associated actions that are either DatabaseAction, BackupDatabaseAction, or RestoreDatabaseAction. 


2.7.2.1.12.11 First 


Source 

Collection(<Any>) 

Parameters 


Result 

<Any> 
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Description 

Returns the first element of the source collection. 


Example 

self . actions->f irst 


2.7.2.1.12.12 IncludesAII 


Source 

Collection(<Any>) 

Parameters 

Collection(<Any>) value 

Result 

Boolean 


Description 

Returns true if every element in the parameter exists in the source. 
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Example 

self . f riends->includesAll (var_Person2 . friends) 

All of var J 3 erson2's friends are also the friends of the current person. 


2.7.2.1.12.13 Including 


Source 

Collection(<Any>) 

Parameters 

<Any> value 

Result 

Collection(<Any>) 


Description 

Returns a copy of the source plus the value specified in the parameter. 


Example 

someContext . people->including (var_Person) 


2.7.2.1.12.14 IndexOf 


Source 

Collection(<Any>) 

Parameters 

<Any> value 

Result 

Int32 


Description 

Returns the index of the parameter within the source collection. The first result in the collection is 1, if the parameter is not 
within the collection zero will be returned. 
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Example 

self . purchaseOrder . lines->indexOf (self) 


If PurchaseOrder.Lines is an ordered association then this OCL expression is a reliable way of determining the line number 
on the PurchaseOrderLine class. 


Notes 

To return a zero based index use ->indexOfO 


2.7.2.1.12.15 Last 


Source 

Collection(<Any>) 

Parameters 


Result 

<Any> 


Description 

Returns the last element of the source collection. 


Example 

self . actions->last 


2.7.2.1.12.16 Prepend 


Source 

Collection(<Any>) 

Parameters 

<Any> itemToAdd 

Result 

Collection(<Any>) 


Description 

Returns the source collection with the addition of the itemToAdd, which appears as the first element within the result. 


2.7.2.1.12.17 Subsequence 


Source 

Collection(<Any>) 

Parameters 

• Int32 firstlndex 

• Int32 numberOfltems 

Result 

Collection(<Any>) 


Description 

Returns a subset of the source collection, starting at the first index specified and containing no more than the number of 
items specified. The first index available is 1 . 
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2.7.2.1 .1 2.1 8 SymmetricDifference 


Source 

Collection(<Any>) 

Parameters 

Collection(<Any>) comparison 

Result 

Collection(<Any>) 


Description 

Returns a collection of all items that appear in only the source or parameter, excluding any items that appear in both. 


2.7.2.1.13 Compare 


Source 

Int32 

Parameters 

Int32 comparison 

Result 

Int32 


2 


Description 

Compares the source to the parameter and returns either 


F 

The source is less than the specified value. 

■ 

The source and parameter are equal. 

H 

The source is greater than the specified value. 


Example 

age . Compare ( 18 ) 


Notes 

Overloads exist for Decimal, DateTime, TimeSpan, and String. 


Source 

String 

Parameters 

• String comparison 

• Boolean ignoreCase 

Result 

Int32 


Description 

Performs the same task except allows you to perform a case-insensitive comparison. 
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Source 

String 

Parameters 

• Int32 firstCharacterPositionOfSource 

• String comparison 

• Int32 firstCharacterPositionOfComparison 

• Int32 lengthOfSubstringOfComparison 

Result 

Int32 


Description 

A substring of the source is used instead of the whole value using ClrSubstring (a see page 102). It is then compared to a 
substring of the parameter. 


2 


Source 

String 

Parameters 

• Int32 firstCharacterPositionOfSource 

• String comparison 

• Int32 firstCharacterPositionOfComparison 

• Int32 lengthOfSubstringOfComparison 

• Boolean ignoreCase 

Result 

Int32 


Description 

Identical to the previous overload except that the comparison may be made in a case insensitive manner. 


2.7.2.1.14 Constraints 


Source 

<Object> 

Parameters 


Result 

Collection(Boolean) 


Description 

Evaluates each of the constraints on the specified business object. The return value itself isn't of much use, but it does 
provide a way of quickly determining the validity of an object's state. 


Example 

self . constraints->select (c I not c)->isEmpty 
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Returns True if the object has no broken constraints. 

2.7.2.1.15 Create 

This operation creates a value of a specific type. This enables your OCL to be specific about the type of value you are 
identifying in the expression. 

Example 



In the OcIPsService the Create operation may be used with the following types. 


Type Parameters 

DateTime —Overload 01 — 

• Int64 numberOfTicks 
—Overload 02— 

• Int32 year 

• Int32 month 

• Int32 day 
—Overload 03— 

• Int32 year 

• Int32 month 

• Int32 day 

• Int32 hour 

• Int32 minute 

• Int32 second 
—Overload 04— 

• Int32 year 

• Int32 month 

• Int32 day 

• Int32 hour 

• Int32 minute 

• Int32 millisecond 
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Decimal —Overload 01 — 

• Single value 
—Overload 02— 

• Double value 
—Overload 03— 

• Int32 value 
—Overload 04— 

• Ulnt32 value 
—Overload 05— 

• Int64 value 
—Overload 06— 

• Ulnt64 value 
—Overload 07— 

• Int32 lo 

• Int32 mid 

• Int32 hi 

• Boolean isNegative 
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Guid —Overload 01 — 

• String value 
—Overload 02— 

• Ulnt32 a 

• Ulntl 6 b 

• Ulntl 6 c 

• Byte d 

• Byte e 

• Byte f 

• Byte g 

• Byte h 

• Byte i 

• Byte j 

• Byte k 
—Overload 03— 

• Int32 a 

• Inti 6 b 

• Inti 6 c 

• Byte d 

• Byte e 

• Byte f 

• Byte g 

• Byte h 

• Byte i 

• Byte j 

• Byte k 
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TimeSpan —Overload 01 — 

• Int64 numberOfTicks 
—Overload 02— 

• Int32 hours 

• Int32 minutes 

• Int32 seconds 

—Overload 03— 

• Int32 days 

• Int32 hours 

• Int32 minutes 

• Int32 seconds 

—Overload 04— 

• Int32 days 

• Int32 hours 

• Int32 minutes 

• Int32 seconds 

• Int32 milliseconds 

® trin 9 • Char characterTo Repeat 

• Int32 numberOfTimesToRepeat 
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2.7.2.1.16 Date and time operations 


2.7.2.1.16.1 AddDays 


Source 

DateTime 

Parameters 

Double days 

Result 

DateTime 


Description 

Returns the source with the specified number of days added to it. 


Example 

startTime . AddDays (7) 


2.7.2.1.16.2 AddHours 


Source 

DateTime 

Parameters 

Double hours 

Result 

DateTime 
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Description 

Returns the source with the specified number of hours added to it. 


Example 

startTime . AddHours (2.5) 


2.7.2.1.16.3 AddMilliseconds 


Source 

DateTime 

Parameters 

Double milliseconds 

Result 

DateTime 


Description 

Returns the source with the specified number of milliseconds added to it. 


Example 

startTime . AddMilliseconds (100) 


2.7.2.1.16.4 AddMinutes 


Source 

DateTime 

Parameters 

Double minutes 

Result 

DateTime 
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Description 

Returns the source with the specified number of minutes added to it. 


Example 

startTime .AddMinutes (45) 


2.7.2.1.16.5 AddMonths 


Source 

DateTime 

Parameters 

Int32 months 

Result 

DateTime 


Description 

Returns the source with the specified number of months added to it. 
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Example 

startTime . AddMonths (1) 


2.7.2.1.16.6 AddSeconds 


Source 

DateTime 

Parameters 

Double seconds 

Result 

DateTime 


Description 

Returns the source with the specified number of seconds added to it. 

Example 

startTime .AddSeconds (30) 
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2.7.2.1.16.7 AddTicks 


Source 

DateTime 

Parameters 

Int64 ticks 

Result 

DateTime 


Description 

Returns the source with the specified number of ticks added to it. The Int64 parameter is the number of 100-nanosecond 
ticks to add. 


Example 

startTime .AddTicks (1000) 


2.7.2.1.16.8 AddYears 


Source 

DateTime 

Parameters 

Int32 years 

Result 

DateTime 


Description 

Returns the source with the specified number of years added to it. 


Example 

dateOfBirth . AddYears (100) 
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2.7.2.1.16.9 Date 


Source 

DateTime 

Parameters 


Result 

DateTime 


Description 

Returns only the date part of a specified DateTime value. 


Example 


self . dateOfBirth . date 


Notes 

It is possible to obtain the current date using the following OCL 


DateTime . Now . Date 


or 


DateTime . Today 


2.7.2.1.16.10 Day 


Source 

DateTime 

Parameters 


Result 

Int32 


Description 

Returns the day number of the date. 


Example 

#2025-12-21 .day 


Returns 21. 


2.7.2.1.16.11 Days 


Source 

TimeSpan 

Parameters 


Result 

Int32 
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Description 

Returns the number of whole days in the time span. 


Example 

TimeSpan . Create ( 99, 12, 00, 00). days 


Returns 99. 


2.7.2.1.16.12 DayOfYear 


Source 

DateTime 

Parameters 


Result 

Int32 


Description 

Returns the day number of the year. 


Example 

#2025-12-21. dayOfYear 


Returns 355. 


2.7.2.1.16.13 DaysInMonth 


Source 

DateTime 

Parameters 

• Int32 year 

• Int32 month 

Result 

Int32 


Description 

Returns the number of days in the specified month. 


Example 

DateTime . daysInMonth (2000, 2) 


Returns 29. 
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2.7.2.1.16.14 Duration 


Source 

TimeSpan 

Parameters 


Result 

TimeSpan 


Description 

Returns the duration of the source time span. The result will always be a positive. 


Example 

TimeSpan . Create (-12 , 00, 00). duration 


Returns 12:00:00. 


2.7.2.1.16.15 FormatDateTime 


Source 

DateTime 

Parameters 

String formatstring 

Result 

String 
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Description 

Returns the source data formatted using the specified format string. 


Example 

Date Time . now . f ormat Date Time ( ' yyyy-MM-dd hh : mm : ss ' ) 


2.7.2.1.16.16 FromBinary 


Source 

DateTime 

Parameters 

Int64 serializedDateTimeValue 

Result 

DateTime 


Description 

Recreates a DateTime value from a serialized value. 


Example 

DateTime . FromBinary (DateTime . Now . ToB inary) 
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2.7.2.1.16.17 FromDays 


Source 

TimeSpan 

Parameters 

Double numberOfDays 

Result 

TimeSpan 


Description 

Creates a new TimeSpan from the number of days specified. 


Example 

TimeSpan . f romDays (99.5) 


Returns 99:12:00:00. 


2.7.2.1.16.18 FromFileTime 


Source 

DateTime 

Parameters 

Int64 fileDateTime 

Result 

DateTime 


2 


Description 

Converts a file system date / time value to a DateTime. 


Example 

DateTime . fromFileTime (self . f ileDateTime) 


2.7.2.1.16.19 FromFileTimeUtc 


Source 

DateTime 

Parameters 

Int64 fileDateTime 

Result 

DateTime 


Description 

Converts the specified Windows file time to an equivalent UTC time. 


Example 

DateTime . f romFileTimeUtc (self . f ileDateTime ) 


72 















2.7 Query services 


ECO Services 


IQcIService 


2.7.2.1.16.20 FromHours 


Source 

TimeSpan 

Parameters 

Double numberOfHours 

Result 

TimeSpan 


Description 

Creates a new TimeSpan from the number of hours specified. 


Example 

TimeSpan . fromHours (36) 


Returns 1:12:00:00. 


2.7.2.1.16.21 FromMilliseconds 


Source 

TimeSpan 

Parameters 

Double numberOfMilliseconds 

Result 

TimeSpan 


2 


Description 

Creates a new TimeSpan from the number of milliseconds specified. 


Example 

TimeSpan . f romMilliseconds ( 1000 ) 


Returns 00:00:01 . 


2.7.2.1.16.22 From Minutes 


Source 

TimeSpan 

Parameters 

Double numberOfMinutes 

Result 

TimeSpan 


Description 

Creates a new TimeSpan from the number of minutes specified. 


Example 

TimeSpan . f romMinutes (1.5) 
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Returns 00:01 :30. 


2.7.2.1.16.23 FromSeconds 


Source 

TimeSpan 

Parameters 

Double numberOfSeconds 

Result 

TimeSpan 


Description 

Creates a new TimeSpan from the number of seconds specified. 


Example 

TimeSpan . fromSeconds ( 90) 


Returns 00:01 :30. 


2.7.2.1.16.24 FromTicks 


Source 

TimeSpan 

Parameters 

Int64 ticks 

Result 

TimeSpan 


Description 

Creates a new TimeSpan from the number of ticks specified. 

2.7.2.1.16.25 Hour 


Source 

DateTime 

Parameters 


Result 

Int32 


Description 

Returns the hour part of the source. 

2.7.2.1.16.26 Hours 


Source 

TimeSpan 

Parameters 


Result 

Int32 
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Description 

Returns the hour part of the source. 


2.7.2.1.16.27 InDateRange 


Source 

DateTime 

Parameters 

• DateTime firstDate 

♦ DateTime lastDate 

Result 

Boolean 


Description 

Returns True if the source DateTime is >= firstDate and <= lastDate. 


Example 

self . appointments->select (a | a . dueDate . inDateRange (DateTime . today, 
DateTime .today . addDays ( 1 ) ) 


2.7.2.1.16.28 InTimeRange 


Source 

TimeSpan 

Parameters 

• TimeSpan firstTime 

• TimeSpan lastTime 

Result 

Boolean 


Description 

Returns True if the source TimeSpan is >= firstTime and <= lastTime. 


Example 

self . todaysAppointments->select (a | a . startTime . inTimeRange (DateTime . now, 
DateTime . now . addHours ( 1 ) ) 


2.7.2.1 .1 6.29 IsDaylightSavingTime 


Source 

DateTime 

Parameters 


Result 

Boolean 


Description 

Returns a value indicating whether a specified date and time is within a daylight saving time period. 


Example 


DateTime . now . isDaylightSavingTime 
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2.7.2.1.16.30 IsLeapYear 


Source 

<Static operation> DateTime 

Parameters 


Result 

Boolean 


Description 

Returns a value indicating whether a specified year is a leap year. 


Example 

Date Time . IsLeapYear (2008) 


2.7.2.1.16.31 Millisecond 


Source 

DateTime 

Parameters 


Result 

Int32 


Description 

Returns a number between 0 and 999 indicating the milliseconds part of the specified DateTime. 

2.7.2.1.16.32 Milliseconds 


Source 

TimeSpan 

Parameters 


Result 

Int32 


Description 

Returns a number between 0 and 999 indicating the milliseconds part of the specified TimeSpan. 

2.7.2.1.16.33 Minute 


Source 

DateTime 

Parameters 


Result 

Int32 


Description 

Returns a number between 0 and 59 indicating the minute part of the specified DateTime. 
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2.7.2.1.16.34 Minutes 


Source 

TimeSpan 

Parameters 


Result 

Int32 


Description 

Returns a number between 0 and 59 indicating the minute part of the specified TimeSpan. 

2.7.2.1.16.35 Month 


Source 

DateTime 

Parameters 


Result 

Int32 


2 


Description 

Returns a number between 1 and 12 indicating the month of the specified DateTime. 


2.7.2.1.16.36 Negate 


Source 

TimeSpan 

Parameters 


Result 

TimeSpan 


Description 

Returns the negated value of the source. A positive TimeSpan will be result in a negative, and a negative in a positive. 

2.7.2.1.16.37 Now 


Source 

<Static operation> DateTime 

Parameters 


Result 

DateTime 


Description 

Returns the current date and time. 


Example 

DateTime. now 
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2.7.2.1 .1 6.38 Second 


Source 

DateTime 

Parameters 


Result 

Int32 


Description 

Returns a number between 0 and 59 indicating the second part of the specified DateTime. 

2.7.2.1.16.39 Seconds 


Source 

TimeSpan 

Parameters 


Result 

Int32 


2 


Description 

Returns a number between 0 and 59 indicating the second part of the specified TimeSpan. 

2.7.2.1.16.40 SumTime 


Source 

Collection(TimeSpan) 

Parameters 


Result 

TimeSpan 


Description 

Produces a TimeSpan that is a sum of all entries in the collection. 

2.7.2.1.16.41 Ticks 


Source 

DateTime 

Parameters 


Result 

Int64 


Description 

Returns the total number of ticks that represent the source value. 


Notes 

An overload also exists for TimeSpan. 
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2.7.2.1.16.42 Time 


Source 

DateTime 

Parameters 


Result 

TimeSpan 


Description 

Returns the time part of the source. 


2.7.2.1.16.43 TimeOfDay 


Source 

DateTime 

Parameters 


Result 

TimeSpan 


2 


Description 

Returns the time part of the source. 


2.7.2.1.16.44 TimeStampToTime 


Source 

Int32 

Parameters 


Result 

DateTime 


Description 

This object-versioning operation will take an object time-stamp number (integer) and return the date and time at which the 
time stamp was created. 


Example 

self . ob jectTimeStamp . timeStampToTime 

This example retrieves the current time stamp for the object instance (the last time it was modified) and returns the date and 
time of that time stamp. 


2.7.2.1.16.45 TimeToTimeStamp 


Source 

DateTime 

Parameters 


Result 

Int32 


Description 

This object-versioning operation will take a date and time and return the appropriate time-stamp number that corresponds. 


Example 
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DateTime . now . addDays (-1 ) . timeToTimeStamp 


2.7.2.1.16.46 ToBinary 


Source 

DateTime 

Parameters 


Result 

Int64 


Description 

Serializes the source to a 64 bit integer. 


2.7.2.1.16.47 Today 


Source 

<Static operation> DateTime 

Parameters 


Result 

DateTime 


Description 

Returns only the date part of the current date. 

2.7.2.1.16.48 ToFileTime 


Source 

DateTime 

Parameters 


Result 

Int64 


Description 

Returns the source converted to a Windows file system date/time. 

2.7.2.1.16.49 ToFileTimelltc 


Source 

DateTime 

Parameters 


Result 

Int64 


Description 

Returns the source converted to a Windows file system date/time. 

2.7.2.1.16.50 ToLocalTime 


Source 

DateTime 

Parameters 


Result 

DateTime 


Description 

Returns the source converted to a local date/time. 
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2.7.2.1.16.51 ToLongDateString 


Source 

DateTime 

Parameters 


Result 

String 


Description 

Uses the Windows regional settings to convert the source into a long date string. 


2.7.2.1.16.52 ToLongTimeString 


Source 

DateTime 

Parameters 


Result 

String 


Description 

Uses the Windows regional settings to convert the source into a long time string. 


2 


2.7.2.1.16.53 ToShortDateString 


Source 

DateTime 

Parameters 


Result 

String 


Description 

Uses the Windows regional settings to convert the source into a short date string. 


2.7.2.1.16.54 ToShortTimeString 


Source 

DateTime 

Parameters 


Result 

String 


Description 

Uses the Windows regional settings to convert the source into a short time string. 


2.7.2.1.16.55 TotalDays 


Source 

TimeSpan 

Parameters 


Result 

Double 


Description 

Returns the total number of days in the source, including the fractional part. 
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2.7.2.1.16.56 TotalHours 


Source 

TimeSpan 

Parameters 


Result 

Double 


Description 

Returns the total number of hours in the source, including the fractional part. 

2.7.2.1.16.57 TotalMilliseconds 


Source 

TimeSpan 

Parameters 


Result 

Double 


Description 

Returns the total number of milliseconds in the source, including the fractional part. 


2 


2.7.2.1.16.58 TotalMinutes 


Source 

TimeSpan 

Parameters 


Result 

Double 


Description 

Returns the total number of minutes in the source, including the fractional part. 

2.7.2.1.16.59 TotalSeconds 


Source 

TimeSpan 

Parameters 


Result 

Double 


Description 

Returns the total number of seconds in the source, including the fractional part. 


2.7.2.1.16.60 TollniversalTime 


Source 

DateTime 

Parameters 


Result 

DateTime 


Description 

Returns the source converted to a coordinated universal time. 
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2.7.2.1.16.61 UtcNow 


Source 

<Static operation> DateTime 

Parameters 


Result 

DateTime 


Description 

Returns the current date and time expressed as universal coordinated time. 


Example 

DateTime . utcNow 


2.7.2.1.16.62 Year 


Source 

DateTime 

Parameters 


Result 

Int32 


Description 

Returns the whole number of years in the source. 


2.7.2.1.17 EmptyList 


Source 

<Type> 

Parameters 


Result 

Collection(<Object>) 


Description 

Returns a strongly typed collection of the specified type, the result will have no elements in it. 


Example 

OCL for an association may look something like this 

if (some condition) then 
self . orders 
else 

Order . emptyList 
endif 


2.7.2.1.18 Existing 


Source 

<lnstance> 

Parameters 


Result 

Boolean 
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Description 

Returns true if the object still exists (and false if it has been deleted) 


2.7.2.1.19 Externalld 


Source 

<lnstance> 

Parameters 


Result 

String 


Description 

Returns the Externalld of the source. See the External ID Service (0 see page 4). 

2.7.2.1.20 If 

Provides a way of providing conditional evaluation. 


2 


Example 

if (some condition) 
self . orders 
else 

Order . emptyList 
endif 

Notes 

Since every OCL expression needs to have a value, the "else-clause" of an if-statement is not optional as it is in most 
programming languages. The OCL evaluator will only evaluate the result of either the "then-clause" or the "else-clause" 
depending of the condition. 


2.7.2.1.21 Let 

The "Let" operation identifies the value of a variable in a statement. 

The syntax for the let-statement is: 

let <variablename> = <expression> in <expression> 

The variable will be assigned the value of the first expression and can be referenced any number of times in the second 
expression 

For example 

let nameToFind = 'Peter' in Person . alllnstances->select ( firstName = nameToFind) 
is the equivalent of 

Person . alllnstances->select ( firstName = 'Peter') 

This operator is useful for repeated use of a value. 

let valueToUse = (some costly OCL evaluation) in 
Company . alllnstances->select ( 

( relevantMember > valueToUse) or (otherRelevantMember > valueToUse) 

) 

If the evaluation of the value is costly then using the "let" operation prevents you from 
having to evaluate the value more than once. 
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2.7.2.1.22 Mathematical operations 

2.7.2.1.22.1 Abs 


Source 

Inti 6 

Parameters 


Result 

Inti 6 


Description 

Returns the absolute value of a number. 


Example 

self . debt . abs 


2 


Notes 

Additional overloads exist for SByte, Inti 6, Inti 6, Single, Double, and Decimal. 

2.7.2.1.22.2 Acos 


Source 

Double 

Parameters 


Result 

Double 


Description 

Using the source as a Cosine value this operation will return its corresponding angle. 


Example 

self . cosineValue . acos 


2.7.2.1.22.3 Asin 


Source 

Double 

Parameters 


Result 

Double 


Description 

Using the source as a Sine value this operation will return its corresponding angle. 
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Example 

self . sineValue . asin 


2.7.2.1.22.4 Atari 


Source 

Double 

Parameters 


Result 

Double 


Description 

Using the source as a tangent this operation will return its corresponding angle. 


Example 

self . tangent . at an 


2.7.2.1.22.5 Atan2 


Source 

Double 

Parameters 

Double yCoOrdinate 

Result 

Double 


Description 

Uses the source as a relative X coordinate and the parameter as a relative Y coordinate. Using this coordinate the tangent is 
calculated and its corresponding angle is returned. 


Example 

self . xposition . atan2 (yposition) 


2.7.2.1.22.6 BigMul 


Source 

Int32 

Parameters 

Int32 factor 

Result 

Int64 


Description 

Multiplies the source by the factor and returns an Int64. This operation should be used when the source is an Int32 but the 
result is expected to be too large to be represented by an Int32. 
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2.7.2.1.22.7 Ceiling 


Source 

Double 

Parameters 


Result 

Double 


Description 

Rounds the source up to the closest whole number. 


Notes 

An overload also exists for Decimal. 


2.7.2.1.22.8 Cos 


Source 

Double 

Parameters 


Result 

Double 


Description 

Using the source as an angle this operation will return its corresponding Cosine value. 


Example 

self . angle . cos 


2.7.2.1.22.9 Cosh 


Source 

Double 

Parameters 


Result 

Double 


Description 

Using the source as an angle this operation will return its corresponding hyperbolic Cosine value. 


Example 

self . angle .cosh 


2.7.2.1.22.10 Exp 


Source 

Double 

Parameters 

Double power 
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Result 


Double 


Description 

Returns the source raised to the specified power. 


Example 

2 . Exp ( 8 ) 


Returns 256. 


2.7.2.1.22.11 Floor 


Source 

Double 

Parameters 


Result 

Double 


Description 

Rounds the source down to the closest whole number. 


Notes 

An overload also exists for Decimal. 


2.7.2.1.22.1 2 Islnfinity 


Source 

Single 

Parameters 


Result 

Boolean 


Description 

Returns a value indicating whether the specified number evaluates to negative or positive infinity. 


Notes 

An additional overload exists for Double. 


2.7.2.1.22.1 3 IsNaN 


Source 

Single 

Parameters 


Result 

Boolean 
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Description 

Returns a value indicating whether the specified number evaluates to not a number (NaN). 


Notes 

An additional overload exists for Double. 


2.7.2.1.22.14 IsNegativelnfinity 


Source 

Single 

Parameters 


Result 

Boolean 


Description 

Returns a value indicating whether the specified number evaluates to negative infinity. 


Notes 

An additional overload exists for Double. 


2.7.2.1.22.15 IsPositivelnfinity 


Source 

Single 

Parameters 


Result 

Boolean 


2 


Description 

Returns a value indicating whether the specified number evaluates to positive infinity. 


Notes 

An additional overload exists for Double. 


2.7.2.1.22.16 Log 


Source 

Double 

Parameters 


Result 

Double 


Description 

Returns the natural (base e) logarithm of a specified number. 


89 












2.7 Query services 


ECO Services 


IQcIService 


Source 

Double 

Parameters 

Double newBase 

Result 

Double 


Description 

Returns the natural (base e) logarithm of a specified number in a specified base. 


2.7.2.1.22.17 LoglO 


Source 

Double 

Parameters 


Result 

Double 


2 


Description 

Returns the base 10 logarithm of a specified number. 

2.7.2.1.22.18 Max 


Source 

Int32 

Parameters 

Int32 comparison 

Result 

Int32 


Description 

Compares the source with the parameter and returns the greater of the two values. 


Example 

1 . max (2 ) 


Notes 

Additional overloads exist for SByte, Byte, Inti 6, Ulntl 6, Ulnt32, Int64, Ulnt64, Single, Double, and Decimal. 

2.7.2.1.22.19 Min 


Source 

Int32 

Parameters 

Int32 comparison 

Result 

Int32 
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Description 

Compares the source with the parameter and returns the lesser of the two values. 


Example 

2 . min ( 1 ) 


Notes 

Additional overloads exist for SByte, Byte, Inti 6, Ulntl 6, Ulnt32, Int64, Ulnt64, Single, Double, and Decimal. 


2.7.2.1.22.20 Negate 


Source 

Decimal 

Parameters 


Result 

Decimal 


Description 

Returns the negated value of the source. A positive value will be result in a negative, and a negative in a positive. 

2.7.2.1.22.21 Pow 


Source 

Double 

Parameters 

Double exponent 

Result 

Decimal 


Description 

Returns the source raised to the power of the specified exponent. 

2.7.2.1.22.22 Remainder 


Source 

Decimal 

Parameters 

Decimal divisor 

Result 

Decimal 


Description 

Divides the source by the specified divisor and returns the remainder. 
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2.7.2.1.22.23 Round 


Source 

Decimal 

Parameters 


Result 

Decimal 


Description 

Returns the result of rounding the source to the nearest whole number. 


Source 

Decimal 

Parameters 

Int32 fractionalDigits 

Result 

Decimal 


Description 

Returns the result of rounding the source to the specified number of fractional digits. 


Notes 

An overload also exists for Double. 


2.7.2.1.22.24 Sin 


Source 

Double 

Parameters 


Result 

Double 


Description 

Using the source as an angle this operation will return its corresponding Sine value. 


Example 

self . angle .sin 


2.7.2.1.22.25 Sinh 


Source 

Double 

Parameters 


Result 

Double 
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Description 

Using the source as an angle this operation will return its corresponding hyperbolic Sine value. 


Example 

self . angle . sinh 


2.7.2.1.22.26 Sqrt 


Source 

Double 

Parameters 


Result 

Double 


Description 

Returns the square root of the source. 

2.7.2.1.22.27 Tan 


Source 

Double 

Parameters 


Result 

Double 


2 


Description 

Using the source as an angle this operation will return its corresponding Tangent value. 


Example 

self . angle . tan 


2.7.2.1.22.28 Tanh 


Source 

Double 

Parameters 


Result 

Double 


Description 

Using the source as an angle this operation will return its corresponding hyperbolic Tangent value. 


Example 

self . angle . tanh 
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2.7.2.1 .22.29 T run cate 


Source 

Decimal 

Parameters 


Result 

Decimal 


Description 

Returns the whole number part of the source, any fractional part is discarded. 


Notes 

An overload exists for Double. 


2.7.2.1.23 MaxLength 


Source 

<String attribute> 

Parameters 


Result 

Int32 


Description 

Returns the maximum value length a string property may hold, as defined in the model. 


Example 

Person instance = new Person (EcoSpace) ; 

int maxLength = ecoSpace . Ocl . Evaluate ( instance . AsIObject () , 
" self . f irstName .maxLength" ) . GetValue<int> ( ) ; 


Notes 

This OCL operation can be useful for ensuring maximum lengths are not exceeded in your Ul. Simply add an additional 
column to your ECO handle for each string attribute on your class with the expression "self.cmember name>. maxLength" - it 
is then possible to databind the MaxLength of a TextBox for example to this value rather than hard-coding it and having to 
manually update if the model changes. 


2.7.2.1 .24 ModifiedSinceTimeStamp 


Source 

<lnstance> 

Parameters 

Int32 timeStamp 

Result 

Boolean 
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Description 

Returns True if the instance has been modified on or after the specified time stamp, otherwise False. This OCL operation 
supports the object versioning mechanism. 


2.7.2.1.25 NewGuid 


Source 

<Static operation> Guid 

Parameters 


Result 

Guid 


Description 

Returns a new Guid. 


Example 

'here is a new guid ' +Guid . NewGuid . asString 


2.7.2.1.26 ObjectFromExternalld 


Source 

<Type> 

Parameters 

string externalld 

Result 

<lnstance> 


2 


Description 

Returns the object with the given persistent ID. The ID consists of the class type and the primary key of the object, and may 
be obtained using the Externalld (0 see page 84) operation. This operation is useful in ASP.NET applications where the ID 
of an object is passed as a query parameter in a URL. 

Example 

Person . ObjectFromExternalld (var_ExternalId) 

This expression is very useful to use in an EcoDataSource on an ASP. Net page where the variable var_Externalld can be 
bound to a parameter in the URL. 


2.7.2.1.27 ObjectTimeStamp 


Source 

<lnstance> 

Parameters 


Result 

Int32 


Description 

Returns the version time stamp of the source. This value will typically be lnt32.MaxValue, except when you use a historical 
object version as the source. 
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2.7.2.1.28 OclAsType 


Source 

<lnstance> 

Parameters 


Result 

<lnstance> 


Description 

Casts the source to the specified sub-class. 


Example 

BaseClass . alllnstances->f irst . oclAsType (Subclass) . attributeOnSubClass 


Source 

Collection(<lnstance>) 

Parameters 


Result 

Collection(<lnstance>) 


Description 

Casts the source collection to the specified sub-class. 


Example 

BaseClass . alllnstances . oclAsType (Subclass) . attributeOnSubClass 


Notes 

An InvalidCastException will be thrown if the source cannot be cast to the specified type. 

2.7.2.1.29 OcllsKindOf 


Source 

<lnstance> 

Parameters 

<Type> 

Result 

Boolean 


Description 

Returns True if the source may be type cast to the type specified as a parameter. 
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Example 

//True. Subclass may be cast to a BaseClass. 
bool subClassIsKindOfBaseClass = EcoSpace . Ocl . Evaluate ( 
subclass . As I Ob ject ( ) , 

"self.oclIsKindOf (BaseClass) " ) . GetValue<bool> ( ) ; 

//False. BaseClass may not be cast to a Subclass 

bool baseClassIsKindOf Subclass = EcoSpace . Ocl . Evaluate ( 
based ass . AsIOb ject ( ) , 

"self.oclIsKindOf (Subclass ) " ) . Ge t Value <bool> ( ) ; 


2.7.2.1.30 OcllsTypeOf 


Source 

<lnstance> 

Parameters 

<Type> 

Result 

Boolean 


Description 

Returns True if the source is an instance of the type specified by the parameter. 


Example 

//True. subclass is an instance of the Subclass type, 
bool subClassIsTypeOf Subclass = EcoSpace . Ocl . Evaluate ( 
subclass .AsIOb ject ( ) , 

" self . oclIsTypeOf (Subclass ) " ) . GetValue<bool> ( ) ; 

//False. subclass is not an instance of the BaseClass type, despite being descended 
from BaseClass. 

bool subClassIsTypeOfBaseClass = EcoSpace . Ocl . Evaluate ( 
subclass .AsIOb ject ( ) , 

" self . oclIsTypeOf (BaseClass) ") . GetValue<bool> ( ) ; 


2 


2.7.2.1.31 Parse 


Source 

<Static operation> <Type> 

Parameters 

String value 

Result 

clnstance of Type> 


Description 

The Parse operation executes the static Parse(String) method on the specified type. This operation is available on all 
standard .NET types that implement the method. 


Example 

Date Time .Parse ( ' 2001-01-31 ' ) 

Date Time .Parse ( '2001-01-31T12:30:59' ) 
Byte .Parse('255') 
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2.7.2.1.32 SafeCast 


Source 

<lnstance> 

Parameters 

<Type> 

Result 

<lnstance> 


Description 

Casts the source to the specified type. If the source is not compatible with the type the operation will silently fail and return 
null/nil. 


Example 

var baseClass = new BaseClass (EcoSpace) ; 
var subclass = 

EcoSpace . Ocl . Evaluate ( 

baseClass . As IObject ( ) , 

"self. safeCast ( Subclass ) " ) . GetValue<SubClass> ( ) ; 

Results in subclass being null. 


Source 

Collection(<lnstance>) 

Parameters 

<Type> 

Result 

Collection(<lnstance>) 


2 


Description 

Casts each instance in the source collection to the specified type. If the source is not compatible with the type the operation 
will silently fail and add null/nil for the individual instance before continuing with the next instance in the source. 


Example 

var baseClass = new BaseClass (EcoSpace) ; 
var subclass = new Subclass (EcoSpace) ; 
var subClassListCount = 

EcoSpace . Ocl . Evaluate ( 

baseClass .As IObject ( ) , 

" BaseClass. alllnstances.safeCa st ( Subclass ) " ) 

. GetAsCollection ( ) .Count; 

Results in subClassListCount holding the value 2, the resulting collection holds a valid object and a nil reference. 


2.7.2.1.33 State machine operations 

2.7.2.1.33.1 OcIGetStates 


Source 

<lnstance> 

Parameters 


Result 

Collection(String) 
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Description 

Given a source instance this operation will return a string for each state the object is in. 


Example 


♦ 


Reviewing 




r ^ 

Publish 

[not self .Author .AutoPublishArticles] 

i- Auth 

or ing 



-O-ReviewinqReqio 

< 

' 

nQ 

► 

1 

Checkingspelling 


SpellingChecked 

i 

CheckingGramm.ii 

i 

GrammarChecked 

t 

s> 


Rqject 

^ Rejected 


Publish ^ f 

[self .Author .AutoPublish Articles] ; y 

Published 


2 


Result 

• Authoring 


Reviewing 


•P ReviewinqReqion Q 

+ 


Checkingspelling 


Publish 

[not self Author AutoPublishArticles] 


— ^) Authoi ing 


Publish 

[self .Author .AutoPublishArticles] 


SpellingChecked 


Check ingGramm<u 


GrammarChecked 


4 


-> Published 


Reject 


Rejected 


Result 

• Reviewing. CheckingGrammar 
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If the state machine contains parallell states, the result from this operation can contain more than one state. 


2.7.2.1.33.2 OcIGetTriggers 


Source 

<lnstance> 

Parameters 


Result 

Collection(String) 


Description 

Given a source instance this operation will return a string for each available trigger depending on its current state. Guard 
expressions are not evaluated in order to include/exclude triggers from the result. 


Example 


Reviewing 


■O ReviewingRegion Q 

♦ 


Publish 

[not self .Author .AutoPublishArticles] 


Anthoi ing 


Publish 

[self .Author .AutoPublishArticles] 


CheckingSpelling 


SpellingChecked 


CheckingGi 


GrammarChecked 


4 


Published 


Reject 




Rejected 


2 


Result 

• GrammarChecked 

• Reject 


2.7.2.1.33.3 OcllsInState 


Source 

<lnstance> 

Parameters 

EnumLiteral StateName 

Result 

Boolean 


Description 

Given a source instance and the name of a state this operation will return True or False depending on whether or not the 
instance's state machine is in that state. 
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Example 


Reviewing 


-O ReviewinqReqion 

# 


Checkingspelling 


Publish 

[not self Author AutoPublishArticles] 


Authoiing 


SpellingChecked 


Check ingGt 


GrammarChecked 


Publish 

[self .Author .AutoPublishArticles] 


Published 


Reject 


Rejected 


//True 

bool isReviewing = 

EcoSpace . Ocl . Evaluate ( 
article . AsIObject () , 

"self. ocl Is Instate ( #Reviewing) " ) . GetValue<bool> ( ) ; 


//True 

bool isCheckingGrammar = 

EcoSpace . Ocl . Evaluate ( 
article . AsIObject () , 

"self. ocl Is Instate ( #CheckingGrammar ) " ) . GetValue<bool> ( ) ; 


/ /False 

bool isPublished = 

EcoSpace . Ocl . Evaluate ( 
article .AsIObject () , 

"self.oclIsInState(#Published) " ) . GetValue<bool> ( ) ; 


2 


2.7.2.1.34 String operations 


2.7.2.1.34.1 Chars 


Source 

String 

Parameters 

Int32 index 

Result 

Char 


Description 

Returns the character at the specified index of the source. The index is zero based. 
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Example 

'Hello' .chars (0) 


2.7.2.1.34.2 ClrSubstring 


Source 

String 

Parameters 

Int32 firstlndex 

Result 

String 


Description 

Uses the CLR String. Substring routine to return a substring of the source. 

Example 

'Hello' . substring (2 ) 


2 


Returns "No". 


Source 

String 

Parameters 

Int32 firstlndex 
Int32 length 

Result 

String 


Description 

Uses the CLR String. Substring routine to return a substring of the source. 


Example 

' Hello '. substring (2 , 2) 


Returns "II". 


2.7.2.1.34.3 Concat 


Source 

String 

Parameters 

String value 

Result 

String 


102 

















2.7 Query services 


ECO Services 


IQcIService 


Description 

Returns the result of appending the parameter to the source. 


Example 

' Hello concat ( ' World') 


Notes 

Additional overloads exist to enable you to specify between one and three values to append to the end of the source. 

2.7.2.1.34.4 Contains 


Source 

String 

Parameters 

String value 

Result 

Boolean 


Description 

Returns True if the text specified exists within the source. 


Example 

' Hello ' . contains ( 1 llo 1 ) 


2.7.2.1.34.5 EndsWith 


Source 

String 

Parameters 

String value 

Result 

Boolean 


Description 

Returns True if the source ends with the string specified. 


Example 

'Hello ' . endsWith ( ' lo ' ) 


Returns True. 












2.7 Query services 


ECO Services 


IQcIService 


2.7.2.1.34.6 Format 


Source 

String 

Parameters 

• String source 

• Object value 

Result 

String 


Description 

Uses the .NET String. Format method on the source to produce a new string. The "value" parameter may be repeated 
multiple times. 


Example 

String . format (' The time now is {0:g}', DateTime . Now) 


2.7.2.1.34.7 GetNumericValue 


Source 

Char 

Parameters 


Result 

Double 


Description 

Converts the specified numeric Unicode character to a double-precision floating point number. 

2.7.2.1.34.8 IndexOf 


Source 

String 

Parameters 

Char character 

Result 

Int32 


Description 

Uses the CLR String. Substring routine. Returns the index of the first occurrence of the specified Unicode character in the 
source string. 

Example 

'Hello'.indexOf('e') 


Source 

String 

Parameters 

String substring 
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Result 
Description 

Uses the CLR String. Substring routine. Returns the index of the first occurrence of the specified sub string in the source 
string. 

Example 

'Hello'.indexOf('llo') 



Source 

String 

Parameters 

• Char character 

• Int32 startPosition 

Result 

Int32 


2 


Description 

Uses the CLR String. Substring routine. Returns the index of the first occurrence of the specified Unicode character in the 
source string. The search starts at the specified zero-based character position. 

Example 

'Hello hello’. indexOf(T, 4) 


Source 

String 

Parameters 

• String substring 

• Int32 startPosition 

Result 

Int32 


Description 

Uses the CLR String. Substring routine. Returns the index of the first occurrence of the specified sub string in the source 
string. The search starts at the specified zero-based character position. 

Example 

'Hello hello'. indexOf('H', 4) 
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Source 

String 

Parameters 

• Char character 


• Int32 startPosition 


• Int32 subStringLength 

Result 

Int32 


Description 

Uses the CLR String. Substring routine. Returns the index of the first occurrence of the specified Unicode character in the 
source string. The search starts at the specified zero-based character position and only inspects the specified number of 
characters. 

Example 

'Hello hello'. indexOf(T, 5, 3) 


2 


Source 

String 

Parameters 

• String substring 


• Int32 startPosition 


• Int32 subStringLength 

Result 

Int32 


Description 

Uses the CLR String. Substring routine. Returns the index of the first occurrence of the specified sub string in the source 
string. The search starts at the specified zero-based character position and only inspects the specified number of characters. 


Example 

'Hello hello’. indexOf('ll', 5, 5) 

2.7.2.1.34.9 Insert 


Source 

String 

Parameters 

♦ Int32 startPosition 

• String stringTolnsert 

Result 

String 


Description 

Returns a new string by inserting the parameter string into the source at the specified zero-based index. 


Example 

' Helo '. insert (2 , '!') 
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2.7.2.1.34.10 IsControl 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether a specified Unicode character is categorized as a control character. 


Example 

self . f irstName . chars ( 0 ) . isControl 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the character at the specified position in a specified string is categorized as a control character. 


Example 

Char . isControl (' Some string with a control character', 2) 


2.7.2.1.34.11 IsDigit 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether a Unicode character is categorized as a decimal digit. 


Example 

self . dateOf Birth . as St ring .chars (2) . isDigit 
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Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the character at the specified position in a specified string is categorized as a decimal digit. 


Example 

Char . isDigit ( ' ABC9 ' , 3) 


2.7.2.1.34.12 IsHighSurrogate 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether the specified Char object is a high surrogate. 


Example 

self . f irstName . chars ( 0 ) . isHighSurrogate 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the Char at the specified position in a string is a high surrogate. 


Example 

Char . isHighSurrogate (' Hello ' , 0) 


2.7.2.1.34.13 IsLetter 


Source 

Char 

Parameters 


Result 

Boolean 
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Description 

Indicates whether a Unicode character is categorized as an alphabetic letter. 


Example 

self . f irstName . chars ( 0 ) . isLowSurrogate 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the character at the specified position in a specified string is categorized as an alphabetic character. 


Example 

Char . isLetter ( ' 0123A' , 4) 


2.7.2.1.34.14 IsLetterOrDigit 


Source 

Char 

Parameters 


Result 

Boolean 


2 


Description 

Indicates whether a Unicode character is categorized as an alphabetic letter or a decimal digit. 


Example 

self . f irstName . chars (0) .isLetterOrDigit 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 
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Description 

Indicates whether the character at the specified position in a specified string is categorized as an alphabetic character or a 
decimal digit. 


Example 

Char . isLetterOrDigit ( ' -AB12- ' , 0 ) 


2.7.2.1.34.15 IsLower 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether the specified Unicode character is categorized as a lowercase letter. 


Example 

self . firstName . chars ( 0 ) .isLower 


2 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the character at the specified position in a specified string is categorized as a lowercase letter. 


Example 

Char . isLower (' Lower ' , 1) 


2.7.2.1.34.16 IsLowSurrogate 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether the specified Char is a low surrogate. 
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Example 

self . f irstName . chars ( 0 ) . isLowSurrogate 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the Char at the specified position in a string is a low surrogate. 


Example 

Char . isLowSurrogate (' Hello ' , 0) 


2.7.2.1.34.17 IsNormalized 


Source 

String 

Parameters 


Result 

Boolean 


2 


Description 

Indicates whether this string is in a particular Unicode normalization form. 


2.7.2.1.34.18 IsNullOrEmpty 


Source 

String 

Parameters 


Result 

Boolean 


Description 

Indicates whether the specified String object is a null reference or an empty string. 


2.7.2.1.34.19 IsNumber 


Source 

Char 

Parameters 


Result 

Boolean 


in 
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Description 

Indicates whether a Unicode character is categorized as a number. 


Example 

self . f irstName . chars ( 0 ) . isNumber 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the character at the specified position in a specified string is categorized as a number. 


Example 

Char . isNumber (' 123 ' , 0) 


2.7.2.1.34.20 IsPunctuation 


Source 

Char 

Parameters 


Result 

Boolean 


2 


Description 

Indicates whether a Unicode character is categorized as a punctuation mark. 


Example 

self . f irstName . chars ( 0 ) . isPunctuation 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 
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Description 

Indicates whether the character at the specified position in a specified string is categorized as a punctuation mark. 


Example 

Char . isPunctuation (' Hello world!', 11) 


2.7.2.1.34.21 IsSeparator 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether a Unicode character is categorized as a separator character. 


2 


Example 

self . f irstName . chars ( 0 ) . is Separator 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the character at the specified position in a specified string is categorized as a separator character. 


Example 

Char . isSeparator ( 1 \t ' , 0) 


2.7.2.1.34.22 IsSurrogate 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether the specified Char is a low surrogate. 


113 



















2.7 Query services 


ECO Services 


IQcIService 


Example 

self . f irstName . chars ( 0 ) . is Surrogate 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the Char at the specified position in a string is a low surrogate. 

Example 

Char . isSurrogate (' Hello ' , 0) 


2.7.2.1.34.23 IsSurrogatePair 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether the two specified Chars form a surrogate pair. . 


2 


Example 

self . f irstName . chars ( 0 ) . isSurrogatePair ( self . f irstName . chars ( 1 ) ) 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether two adjacent Chars at the specified position form a surrogate pair. 

Example 

Char . isSurrogatePair (self . f irstName, 0 ) 
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2.7.2.1.34.24 IsSymbol 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether a Unicode character is categorized as a symbol. 


Example 

self . firstName . chars ( 0 ) .isSymbol 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the character at the specified position in a specified string is categorized as a symbol. 


Example 

Char . isSymbol (' 1 +1=2', 2) 


2.7.2.1.34.25 Isllpper 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether the specified Unicode character is categorized as a uppercase letter. 


Example 

self . firstName . chars (0 ) .isUpper 
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Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the character at the specified position in a specified string is categorized as a uppercase letter. 


Example 

Char . isUpper (' Upper ' , 0) 


2.7.2.1.34.26 IsWhiteSpace 


Source 

Char 

Parameters 


Result 

Boolean 


Description 

Indicates whether the specified Unicode character is categorized as a white space letter. 


Example 

self . f irstName . chars ( 0 ) . isWhiteSpace 


Source 

<Static operation> Char 

Parameters 

• String value 

• Int32 index 

Result 

Boolean 


Description 

Indicates whether the character at the specified position in a specified string is categorized as a white space letter. 


Example 

Char . isWhiteSpace (' Hello world', 5) 
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2.7.2.1.34.27 LastlndexOf 


Source 

String 

Parameters 

String value 

Result 

Boolean 


Description 

Reports the index position of the last occurrence of a specified string within the source string. 


Example 

self . f irstName . lastlndexOf ( ' . ' ) 


Source 

String 

Parameters 

• String value 

• Int32 position 

Result 

Boolean 


Description 

Reports the index position of the last occurrence of a specified string within the source string. This overload searches a 
sub-string of the source, the substring will be the first character (position 0) up to and including the position specified. 


Example 

self . f irstName . lastlndexOf ( ' . ' , 5) 


Source 

String 

Parameters 

• String value 


• Int32 startlndex 


• Int32 length 

Result 

Boolean 


Description 

Reports the index position of the last occurrence of a specified string within the source string. This overload searches a 
sub-string of the source, the substring will be the character specified by the startlndex with the specified length. 
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Example 

self . f irstName . lastlndexOf ( ' . ' , 3, 10) 


2.7.2.1.34.28 Normalize 


Source 

String 

Parameters 


Result 

String 


Description 

Returns a new string whose binary representation is in a particular Unicode normalization form. 

2.7.2.1.34.29 Pad 


Source 

String 

Parameters 

• Int32 newLength 

• String paddingString 

Result 

String 


Description 

Returns a new string based on the source with a guaranteed minimum length. If the source is shorter than the specified new 
length it will be left-padded with the specified text, if it is already equal to or longer than the specified new length the result 
will be the same as the source. 


Example 

//returns 21212Hello 
'Hello' ,pad(10, '12') 


2.7.2.1.34.30 PadLeft 


Source 

String 

Parameters 

Int32 newLength 

Result 

String 


Description 

Returns a new string based on the source with a guaranteed minimum length. If the source is shorter than the specified new 
length the left of the string be padded with spaces, if it is already equal to or longer than the specified new length the result 
will be the same as the source. 


Example 

'Hello' .padLeft (6) 

Returns " Hello" 


'Hello' .padLeft (3) 


Returns "Hello 1 
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Source 

String 

Parameters 

Int32 newLength 
Char paddingCharacter 

Result 

String 


Description 

Returns a new string based on the source with a guaranteed minimum length. If the source is shorter than the specified new 
length the left of the string be padded with the specified character, if it is already equal to or longer than the specified new 
length the result will be the same as the source. 


Example 

'Hello' .padLeft (10, 'a' .chars (0) ) 

Returns "aaaaaHello" 


2.7.2.1.34.31 PadRight 


Source 

String 

Parameters 

Int32 newLength 

Result 

String 


Description 

Returns a new string based on the source with a guaranteed minimum length. If the source is shorter than the specified new 
length the right of the string be padded with spaces, if it is already equal to or longer than the specified new length the result 
will be the same as the source. 


2 


Example 

'Hello' .padRight (6) 

Returns "Hello " 


'Hello' .padRight (3) 

Returns "Hello" 


Source 

String 

Parameters 

Int32 newLength 
Char paddingCharacter 

Result 

String 


Description 

Returns a new string based on the source with a guaranteed minimum length. If the source is shorter than the specified new 
length the right of the string be padded with the specified character, if it is already equal to or longer than the specified new 
length the result will be the same as the source. 
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Example 

'Hello'. padRight(1 0, 'a'.chars(O)) 
Returns "Helloaaaaa" 


2.7.2.1.34.32 PostPad 


Source 

String 

Parameters 

Int32 newLength 
String paddingString 

Result 

String 


Description 

Returns a new string based on the source with a guaranteed minimum length. If the source is shorter than the specified new 
length the right of the string be padded with the specified padding string, truncating the result if necessary. If the source is 
already equal to or longer than the specified new length the result will be the same as the source. 


2.7.2.1.34.33 Reg Exp Match 


Source 

String 

Parameters 

String pattern 

Result 

Boolean 


Description 

Evaluates the specified pattern against the source and returns whether or not the source matches the pattern. 
For information of the syntax for regular expression, please refer to the .net framework documentation. 

2.7.2.1.34.34 Remove 


Source 

String 

Parameters 

Int32 firstCharToRemove 

Result 

String 


Description 

Removes the end of the source string from the firstCharToRemove onwards and returns the result. 


Example 

'Hello World !'. Remove ( 5 ) 

Returns "Hello" 


Source 

String 

Parameters 

Int32 firstCharToRemove 
Int32 numberOfCharsToRemove 
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Result String 

Description 

Removes the specified number of characters from the source string starting from firstCharToRemove. 


Example 

'Hello World! ' .Remove (5, 6) 

Returns "Hello!" 


2.7.2.1.34.35 Replace 


Source 

String 

Parameters 

String textToFind 
String textToReplace 

Result 

String 


Description 

Returns a string based on the source but with all occurences of textToFind replaced with textToReplace. 


Example 

'Hello World !'. Replace (' World ' , 'mother') 

Returns "Hello mother!" 


2.7.2.1.34.36 StartsWith 


Source 

String 

Parameters 

String value 

Result 

Boolean 


Description 

Returns True if the text specified starts with the value specified. 


Example 

' Hello ' . startsWith ( ' He ' ) 


2.7.2.1.34.37 StrToDate 


Source 

String 

Parameters 


Result 

DateTime 
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Description 

Uses DateTime. Parse to convert the source to a DateTime. 


2.7.2.1.34.38 StrToDateTime 


Source 

String 

Parameters 


Result 

DateTime 


Description 

Uses DateTime. Parse to convert the source to a DateTime. 


2.7.2.1.34.39 StrToInt 


Source 

String 

Parameters 


Result 

Int32 


Description 

Uses Int32. Parse to convert the source to an Int32. 


2.7.2.1.34.40 StrToTime 


Source 

String 

Parameters 


Result 

TimeSpan 


Description 

Uses TimeSpan. Parse to convert the source to a TimeSpan. 


2.7.2.1.34.41 Substring 


Source 

String 

Parameters 

Int32 startlndex 
Int32 length 

Result 

String 


Description 

Returns a sub string of the source. 
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2.7.2.1.34.42 ToLower (Char) 


Source 

Char 

Parameters 


Result 

Char 


Description 

Converts a char value to lower case. 


Example 

self . productCode . chars ( 1 ) . toLower 


2.7.2.1.34.43 ToUpper (Char) 


Source 

Char 

Parameters 


Result 

Char 


Description 

Converts a char value to upper case. 


Example 

self . productCode . chars ( 1 ) . toUpper 


2.7.2.1 .34.44 ToLowerlnvariant 


Source 

String 

Parameters 


Result 

String 


Description 

Converts a string to lower case using casing rules of the invariant culture. 


Example 

self . productCode . toLowerlnvariant 


Notes 

An overload exists for Char. 


2.7.2.1.34.45 Tollpperlnvariant 


Source 

String 

Parameters 


Result 

String 
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Description 

Converts a string to upper case using casing rules of the invariant culture. 

Example 

self . productCode . toUpperlnvariant 


Notes 

An overload exists for Char. 


2.7.2.1.34.46 Trim 


Source 

String 

Parameters 


Result 

String 


Description 

Returns the source with all leading and trailing white space characters removed. 

Example 

self . productCode . trim 


2.7.2.1.35 SuperTypes 


Source 

Type 

Parameters 


Result 

Collection(String) 


2 


Description 

Returns a list of class names, one for each supertype of the source. 


2.7.2.1.36 TimeSpan operations 

2.7.2.1.37 TaggedValue 


Source 

<lnstance> 

Parameters 

String taggedValueName 

Result 

String 


Description 

Finds a tagged value with the specified name defined against the instance's class (or one of its super classes) and returns 
the value defined in the model. 
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2.7.2.1.38 ToByte 


Source 

Decimal 

Parameters 


Result 

Byte 


Description 

If the source is within the range Byte.MinValue .. Byte.MaxValue the result will be a byte, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 


2.7.2.1.39 ToDouble 


Source 

Decimal 

Parameters 


Result 

Double 


Description 

If the source is within the range Double. MinValue .. Double. MaxValue the result will be a Double, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 


2.7.2.1.40 Tolnt16 


Source 

Decimal 

Parameters 


Result 

Inti 6 


Description 

If the source is within the range Inti 6. MinValue .. Inti 6. MaxValue the result will be an Inti 6, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 


2.7.2.1.41 Tolnt32 


Source 

Decimal 

Parameters 


Result 

Int32 


Description 

If the source is within the range Int32. MinValue .. Int32. MaxValue the result will be an Int32, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 
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2.7.2.1.42 Tolnt64 


Source 

Decimal 

Parameters 


Result 

Int64 


Description 

If the source is within the range lnt64.MinValue .. lnt64.MaxValue the result will be an Int64, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 


2.7.2.1.43 ToSByte 


Source 

Decimal 

Parameters 


Result 

SByte 


Description 

If the source is within the range SByte.MinValue .. SByte.MaxValue the result will be a signed byte, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 


2.7.2.1.44 ToSingle 


Source 

Decimal 

Parameters 


Result 

Single 


2 


Description 

If the source is within the range Single. MinValue .. Single. MaxValue the result will be a Single, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 


2.7.2.1.45 ToUlnt16 


Source 

Decimal 

Parameters 


Result 

Ulntl 6 


Description 

If the source is within the range Ulntl 6. MinValue .. U Inti 6. MaxValue the result will be an Ulntl 6, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 
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2.7.2.1.46 ToUlnt32 


Source 

Decimal 

Parameters 


Result 

Ulnt32 


Description 

If the source is within the range Ulnt32.MinValue .. Ulnt32.MaxValue the result will be an Ulnt32, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 


2.7.2.1.47 ToUlnt64 


Source 

Decimal 

Parameters 


Result 

Ulnt64 


Description 

If the source is within the range Ulnt64.MinValue .. Ulnt64.MaxValue the result will be an Ulnt64, otherwise a 
System. TargetlnvovationException will be thrown (with an inner exception type of System. OverflowException). Any fractional 
value will be discarded. 


2.7.2.1 .48 TypeName 


Source 

<Type> 

Parameters 


Result 

String 


2 


Description 

Returns the class name of the source type. 


2.7.2.1.49 Xor 


Source 

Boolean 

Parameters 

Boolean comparison 

Result 

Boolean 


Description 

Returns the result of performing a logical exclusive OR on the source and parameter 


Example 

false xor false = false 
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false xor true = true 
true xor false = true 
true xor true = false 


lActionLanguageService 


The Action Language Service is an OCL based expression executor. As well as the OcIPs and Ocl commands, which have 
no side effects, this service is additionally capable of executing statements which alter object state. The Action Language 
Service is particularly useful when designing state machines. For example when an Article enters a Published state it makes 
sense to set the article's PublishedDate to the current date and time. 


This would be achieved by setting an Entry Action on the Published state with a simple action language expression 


4 

Published 
Internal transitions 

entry /publishedDate := DateTime.now 

V J 


Assignments in the action language service are made using the token := 

2.7.3. 1 Operations support by lActionLanguageService 

The lActionLanguageService supports all of the lOcIPsService operations (a see page 28), all of the lOcIServiceOperations 
(a see page 48) operations, and the following additional operations. 


2 


2.7. 3. 1.1 Clear 


Source 

Collection(<Any>) 

Parameters 


Result 



Description 

Removes all elements from the source collection. 


Notes 

The source must be a member of a modeled class. 

/ /Valid 

self . orderLines->clear 
/ /Invalid 

self . orderLines->select (value < 100)->clear 
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2.7. 3. 1.2 Add 


Source 

Collection(<Any>) 

Parameters 

<Any> instanceToAdd 

Result 

Collection(<Any>) 


Description 

Adds the parameter to the source. 


Notes 

The source must be a member of a modeled class. 

/ /Valid 

self . order Line s->add (Order Line .Create) 

/ /Invalid 

self . orderLines->select (value < 100 ) ->add (OrderLine . Create ) 


2.7.3.1.3 Create 


Source 

<Type> 

Parameters 


Result 

<lnstance> 


Description 

Creates an instance of the specified modeled class. 


Example 

Person . Create 


2.7.3.1.4 Delete 


Source 

<Type> 

Parameters 


Result 

Boolean 


Description 

Deletes the specified object instance. 


2.7.3.1.5 Remove 


Source 

Collection(<Any>) 

Parameters 

<Any> instanceToRemove 

Result 

Collection(<Any>) 


Description 
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Removes the specified parameter from the source collection. 


Notes 

The source must be a member of a modeled class. 

/ /Valid 

self . orderLines->remove (self . orderLines->last ) 

/ /Invalid 

self . or de r Line s-> select (value < 100 ) -> remove (self . orderLines->last ) 


2.7.3.1.6 RemoveAt 


Source 

Collection(<Any>) 

Parameters 

<Any> indexToRemove 

Result 

Collection(<Any>) 


Description 

Removes the item at the specified index from the source collection. 


Notes 

The source must be a member of a modeled class. 

/ /Valid 

self . orderLines->removeAt (1) 

/ /Invalid 

self . orderLines->select (value < 100 ) ->removeAt ( 1 ) 


2 


2.7.4 ITypeService 


The type service allows you to perform various functions on the OCL evaluator, such as determining the result type of an 
expression or registering new OCL operations. The members of the ITypeService are implemented directly on each of the 
three OCL services. So instead of obtaining an ITypeService from the EcoSpace you would use the equivalent method on 
the OCL service. 


Determining if the result of an expression is read-only 

When evaluating an OCL expression the result of that evaluation is either mutable or read-only. A result is mutable if the 
expression results in a domain member (a member of a class) and that member is not read-only. 

//Mutable, this is a domain member (modeled) 
self . f irstName 

//Read-only, because this is an expression derived from a domain member 
self . f irstName . toUpper 

//Read-only, because the value is assigned by the DB 
//self . unique ID 

To determine whether or not an expression is readonly use the ExpressionlsReadOnly method on the appropriate OCL 
service. 
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IClassifier classifier = EcoSpace . TypeSystem . GetClassByType (typeof (Person) ) ; 
bool readonly = EcoSpace . Ocl . ExpressionlsReadOnly ( "person" , classifier, 
false) . GetValue<bool> ( ) ; 


Determining model information from an expression 

If the expression results in a domain element (Person. FirstName for example) it is possible to get information about the 
member as follows 

IClassifier classifier = EcoSpace . TypeSystem . GetClassByType (typeof (Person) ) ; 
IStructuralFeature modellnf ormation = EcoSpace . Ocl . ExpressionModellnf o (" self . firstName " , 
classifier, false) ; 

If the expression does not result in a domain element null will be returned. IStructuralFeature is described in the API help. 


2.7 .4.1 InstalledOperations 

Each OCL service implements a different set of OCL operations. It is possible to discover a list of installed operations for a 
given OCL service using the InstalledOclOperations property. This property will contain an entry for every installed operation, 
in addition it will contain operations with duplicate names when an operation has many overloads. 

foreach ( IOclOperation currentOperation in EcoSpace . OclPs . InstalledOclOperations ) 

Console . WriteLine (currentOperation .Name) ; 


2.7. 4.2 Creating a string operation 

Custom OCL operations may only be registered in the lOcIService and lActionLanguageService. This is due to the fact that 
these are evaluated in memory, to implement an lOcIPsService operation would involve a way to translate the operation to 
SQL, and this functionality is not currently supported in ECO. There is a class named OclOperationBase which may be used 
to simplify the process of creating custom OCL operations, when descending from this base class you only need to override 
two methods; Init and Execute. 


2 


The following example illustrates how to create an operation which reverses a string. 

public class ReverseStringOperation : OclOperationBase 

{ 

//Recommended approach. Have a static method that registers the operation into 
//the correct OCL services 

//(as some may be intended for the Action Language Service only) 
public static void InstallOperation ( IEcoServiceProvider serviceProvider ) 

{ 

if (serviceProvider == null) 

throw new ArgumentNullException ( "ServiceProvider" ) ; 

ReverseStringOperation impl = new ReverseStringOperation () ; 
serviceProvider . GetEcoService<IOclService> ( ) . InstallOperation ( impl ) ; 
serviceProvider . Ge t E coS e rvice< I Act ionLanguage Service > ( ) . InstallOperation ( impl ) ; 

} 

//Called when the OCL operation is installed 
protected override void Init() 
f 

//Define the operation name 
string operationName = "reverse"; 

//Specify the source must be a string 
IOclType sourceType = Support . StringType; 

//Initialise using 
// Operation name 

// Parameters - The first is the source 
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// Return type - In this case the same as the source 
Internallnit ( 

operationName, 

new IOclType[] { sourceType }, 
sourceType) ; 

} 

//Executed when the operation needs to be processed 

public override void Evaluate (IOclOperationParameters oclParameters ) 

{ 

//Get the first value (the source) as an element, and cast it to a string 
string value = oclParameters . Values [ 0 ]. Element . GetValue<string> () ; 

//Use a StringBuilder to reverse the string's characters 
StringBuilder resultBuilder = new StringBuilder () ; 
for (int index = value. Length - 1; index >= 0; index — ) 
resultBuilder .Append (value [index] ) ; 

//Create a constant IElement representing the reversed string 
IElement result = 

Support . VariableFactory . CreateConstant (resultBuilder . To St ring ( ) ) ; 

//Set the result of the operation 
oclParameters .Result . SetOwnedElement (result ) ; 



This example would be used like so 

//You should install operations in the EcoSpace constructor ! 

ReverseStringOperation . InstallOperation (EcoSpace ) ; 

string reversed = 

EcoSpace . Ocl . Evaluate ( "Person . alllnstances->f irst . f irstName . reverse" ) . GetValue<string> ( 

) ; 
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2.7. 4.3 Creating a collection operation 

The following operation shows how to create an operation based on a collection, and also how to specify additional 
parameters. Unlike the ReverseStringOperation example the Internallnit method is called with an 
OcIResuItTypeDeduceMethod parameter for the result type instead of an lOcIType. This informs the evaluator to deduce the 
result type from the source. 

public class SampleCollectionOperation : OclOperationBase 

{ 

//Register the operation 

public static void InstallOperation ( IEcoServiceProvider serviceProvider ) 

{ 

if (serviceProvider == null) 

throw new ArgumentNullException ( "ServiceProvider" ) ; 

SampleCollectionOperation impl = new SampleCollectionOperation () ; 
serviceProvider . GetEcoService<IOclService> ( ) . InstallOperation ( impl ) ; 
serviceProvider . Ge t E coS e r vi ce < I Act ionLanguage Service > ( ) . InstallOperation ( impl ) ; 

} 

//Initialise the operation details 

protected override void Init() 

{ 

//The operation name 

string operationName = "sample"; 

//The source must be a list 

IOclType sourceType = Support . ListType; 

//1st parameter must be an integer (number of samples ) 

IOclType numberOf SamplesType = Support . IntegerType; 
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//Return type is the same as the source, but allow duplicates. 

//This is because the source might be a collection of strings 

OclResultTypeDeduceMethod resultType = OclResultTypeDeduceMethod . SourceAsBag; 

//Register 
Internallnit ( 

operationName, 

new IOclType [ ] { sourceType, numberOf SamplesType }, 

resultType) ; 

} 

public override void Evaluate ( IOclOperationParameters oclParameters ) 

{ 

//Get the source as a collection 
IElementCollection source = 

oclParameters .Values [ 0 ] . Element . GetAsCollection ( ) ; 

//Get the number of samples to take 

int numberOf Samples = oclParameters .Values [ 1 ]. Element . GetValue<int> () ; 
if (numberOf Samples > source . Count ) 
numberOf Samples = source . Count ; 

double current Index = 0; 

double stepSize = source. Count / (double) numberOf Samples; 

/ /Create an element to hold the result 
IElementCollection result = 

( IElementCollection) Support . CreateNewVariable (oclParameters .Result . OclType ) ; 

//Add samples to the result 
while (numberOf Samples > 0) 

{ 

int readlndex = (int ) Math . Round (current Index) ; 
if (readlndex >= source . Count ) 

readlndex = source. Count - 1; 
result . Add (source [ readlndex] ) ; 
numberOf Samples — ; 
currentlndex += stepSize; 

} 

oclParameters .Result . SetOwnedElement (result ) ; 



2 


2.8 IPersistenceService 


The persistence service is responsible for mediating between the EcoSpace and the data storage. Rather than a 
create/retrieve/update/delete approach ECO's persistence service implements create/update/delete via a single instruction 
to update the data storage, ECO's internal state management will track which type of operation is appropriate based on 
actions performed against the local object cache (creating a new object, modifying an object, or deleting an object); freeing 
the developer from having to concern themself with which type of call to make. 


Persisting changes to the data storage 

The most simple way to update an object to the data storage is to call the UpdateDatabase method with a single object. 


//Create a new person and persist it 
Person personl = new Person (EcoSpace) ; 

EcoSpace .Persistence. UpdateDatabase (personl ) ; 

//Modify an existing person and persist the changes 
personl . FirstName = "John"; 
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E co Space .Persistence. UpdateD at abase (personl ) ; 

//Delete an existing person and persist the deletion 
personl . AsIOb ject ( ) .Delete (); 

E co Space .Persistence. UpdateD at abase (personl ) ; 


Whenever an UpdateDatabase is performed ECO will additionally remove any undo or redo blocks held by the undo service 
(0 see page 9) which reference the object that is having its changes persisted. This is in order to prevent the consumer of 
the business model from making changes, persisting the changes, and then undoing those changes in the local cache; 
effectively making the local cache out of sync with the data storage. 

Usually the application consuming the business model is solely responsible for deciding when to update the data storage, 
but sometimes part of the business logic dictates that an update made by the model should be persisted immediately. For 
example, if your business model implements a custom form of pessimistic locking 


public 

{ 

bool AcquireLock (PessimisticLock lock) 

//01 

//02 

Throw an exception if lock . LockedBy is not null 
Unload the lock object to make it current 

//03 

//04 

//05 

} 

Set lock . LockedBy to the current user 

Attempt to update the database 

Catch any optimistic locking exception 


In the preceding pseudo code it is necessary to update the data storage immediately in order to ensure the custom 
pessimistic lock is required. If there is an active undo block then the changes performed here will be recorded by that block, 
the call to UpdateDatabase will then remove the block from the undo service to prevent further use of it, which could cause a 
problem for the application using the model as it would rightly expect the undo block to still be present. The correct approach 
would therefore be 


public 

bool AcquireLock (PessimisticLock lock) 


//01 

Throw an exception if lock . LockedBy is 

not null 

/ / 02 

Unload the lock object to make it current 

//** 

Start a new undo block 


// 03 

Set lock . LockedBy to the current user 


//04 

Attempt to update the database 


//05 

Catch any optimistic locking exception 


//** 

In case of an exception remove the undo 

block 

//from the undo service 

} 



Another operation performed by ECO is to ensure that any update to the data storage is logical. If we refer back to the driver 
vehicle model from earlier in this document we can see that the following source code is a complete logical operation 



Driver 

0..1 

DriverCurrentvehicle g ^ 

Vehicle 


CurrentDriver 


J 


CurrentVehicle 

J 


Driver driverl = new Driver (EcoSpace ) ; 

Vehicle vehiclel = new Vehicle (EcoSpace) ; 

EcoSpace .Persistence. UpdateDatabase (driverl ) ; 
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But the following example is not a complete logical operation 


Driver driverl = new Driver (EcoSpace ) ; 

Vehicle vehiclel = new Vehicle (EcoSpace) ; 

//Create an association between the two new objects 
driverl . CurrentVehicle = vehiclel; 

EcoSpace .Persistence. UpdateD at abase (driverl ) ; 


This is code is not a complete logical operation because there is a reference from driverl to vehiclel which has not yet been 
persisted. In order to ensure the update operation is a complete logical unit ECO will make a call to the EnsureEnclosure 
method on the persistence service, which ensures that all objects required to make the update are also included in the 
update. 


In this example the enclosure occurs because the vehicle refers to an object that has not been persisted, but enclosure may 
also occur when a reference changes. In the Driver/Vehicle model it is likely that one of the ends of the association is 
marked as embedded. If the Driver end of the association is marked as embedded it means that the primary key of the 
Driver is embedded into the table holding the Vehicle data, so the Vehicle table would have a column named "Driver". 


Driver 


Primary key 

Name 

1234 

John Smith 


2 


Vehicle 


Primary key 

RegistrationNumber 

Driver 

4321 

DE 51 RED 

1234 


driverl . CurrentVehicle = null; 

EcoSpace .Persistence. UpdateD at abase (driverl ) ; 


In the preceding data tables you can see that the driver "John Smith" is currently assigned the vehicle "DE 51 RED". In the 
code snippet John Smith (a.k.a. driverl) has had his vehicle unassigned. The changes made to driverl are then persisted 
but in order to make the update complete "DE 51 RED" must also be updated as it is Vehicle's database table that actually 
holds the reference. 


Note: It Is possible that neither end of the association is marked as embedded , resulting in a "link table" in the database 
holding the primary key of each side of the association. This is common in many-to-many associations and quite rare in 
one-to-one associations. 


Persisting a collection of objects' changes 

It is also possible to persist changes to multiple instances as a single database operation. The UpdateDatabaseWithList 
method accepts an lObjectList parameter which may be obtained in a number of ways, the most commonly used are 
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Updating all changes 


IObjectList dirtyObjects = EcoSpace . DirtyList . AllDirtyOb jects () ; 
EcoSpace . Persistence . UpdateDatabaseWithList (dirtyObjects ) ; 


Note: This code is the equivalent of EcoSpace. UpdateDatabaseQ 


Updating changes captured by an undo block 

string blockName = Guid.NewGuid ( ) . ToString ( ) ; 

EcoSpace . Undo . StartUndoBlock (blockName ) ; 

//Make changes here 

IUndoBlock undoBlock = EcoSpace . Undo . UndoList [blockName ] ; 
IObjectList dirtyObjects = undoBlock . GetChangedOb jects () ; 
EcoSpace . Persistence . UpdateDatabaseWithList (dirtyObjects ) ; 


Unloading object contents 

Unloading an instance of a business class simply removes its loaded property values from the local EcoSpace cache. An 
object cannot be unloaded if its class has been modeled as Transient, if the EcoSpace has no persistence (which effectively 
makes all instances Transient), an instance can also only be unloaded if it is unmodified. 


EcoSpace .Persistence. Unload (personl) ; 


It is possible to query whether or not an object's contents have been loaded using the IsLoaded method: 


2 


IObjectList objects = ; 

if (lEcoSpace. Persistence. IsLoaded (ob jects [ 0 ] ) ) 


The IObjectList in this case would most likely be the result of evaluating an OCL expression. It would be pointless obtaining 
the lObject reference using personl .AslObject(), lObject is merely an object-locator whereas personl would be of the 
modeled "Person" type, and in order to have a reference to the modeled type the object's contents would first need to be 
loaded into the local EcoSpace cache. 


Efficiently retrieving lists of objects 

Associations in ECO are lazy fetched, meaning that an associated object is only loaded if it is accessed. 


Vehicle vehiclel = {Some code to retrieve a single vehicle}; 

//Accessing its driver will load the driver from the data storage 
Driver driverl = vehiclel . Driver; 


If the association is a multi-role then only the object locators are loaded when the property is first accessed, the contents of 
the objects are loaded when an attempt is made to access an individual object in the collection. 


Customer customer 1 = {Some code to retrieve a single customer}; 
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//Accessing the customer's purchase orders will retrieve ID's only 
if (customerl . Orders . Count > 0) 

{ 

//Accessing an order by index will load the single order's contents 
PurchaseOrder order 1 = customer 1 . Orders [ 0 ] ; 


Iterating through a list of orders using a for loop would be inefficient as it would result in a single data storage fetch per order 
in the collection. ECO has a number of techniques for improving the performance of fetching associated objects. The first, 
and most simple, is to use an enumerator to loop through the elements. 


//Efficient approach, using an enumerator indicates your intention 

//to use multiple orders in the collection. ECO will load the associated 

//objects in batches of 50. 

foreach (var currentOrder in customer 1 . Orders ) 


//Inefficient approach, using a specific index does not reveal any intention 
//to use multiple associated orders, so ECO loads only the order at the 
//specified index. 

for (int i = 0; i < customerl . Orders . Count ; i++) 

{ 

PurchaseOrder currentOrder = customer 1 . Orders [ i ] ; 

} 


The same applies when you evaluate an OCL expression to retrieve a collection of objects. ECO will firstly only retrieve 
object IDs from the data storage, it will only load the objects' contents when you attempt to access them. 


//Only ID's are retrieved from the data storage 

IObjectList list = EcoSpace . OclPs ( "Customer . alllnstances->select ( isActive) ") ; 

//The first customer in the list will have its contents loaded from the data storage 
Customer customerl = list [ 0 ] . GetValue<Customer> ( ) ; 


2 


An IObjectList is merely a collection of object locators which may be converted to instances of modeled classes. Because of 
this when you use an enumerator you are iterating object locators and not instances of modeled classes; as a consequence 
using an enumerator will not automatically fetch object contents because the step to retrieve the class instance is an 
additional one: 


//Retrieve object ID's 
IObjectList list = . . . ; 

foreach (IObject locator in list) 

{ 

//Single operation within the loop to convert to an 
//instance of a modeled class 

Customer currentCustomer = locator . GetValue<Customer> () ; 

} 


If your intention is to iterate over the instances referred to by these object locators (rather than merely to use the list as the 
context for a second OCL evaluation) it is possible to instruct ECO to pre-load the objects in the locator list. 


IObjectList list = ...; 

//Easiest way, if you intend to iterate over all instances . 
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//This pre-loads the objects and returns an IList of the 
//relevant type. 

IList<Customer> customers = list . GetAsIList<Customer> ( ) ; 


Or alternatively to pre-load only a subset 


IOb jectList list = . . . ; 

//Pre-load a subset of the objects in the locator list. 

int firstlndex = 0; 

int lastlndex = list. Count / 2; 

EcoSpace . Persistence . EnsureRange ( list , firstlndex, lastlndex); 


Efficiently loading related objects 

The previous section shows how to efficiently load objects either in a locator list, or associated from a single object. There 
are circumstances where your code needs to perform a nested loop; for example to loop through every PurchaseOrder of 
every customer in a list. 


//Example 1: Using OCL to eliminate the need for an outer loop 
string ocl = "Customer . alllnstances->select ( isActive ). orders " ; 
var orders = EcoSpace . OclPs . Execute (ocl ). GetAsIList<PurchaseOrder> () ; 

//Example 2: Pre-loading an association on a list of object locators 

IObjectList list = EcoSpace . OclPs . Execute ( "Customer . alllnstances->select ( isActive) ") ; 
EcoSpace .Persistence. EnsureRelatedOb jects ( list , "Orders " ) ; 


2 


Related Topics 

For information regarding the GetAIIWithCondition see the Version Service (Usee page 141). 
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2.8.1 Multi user concurrency 

TODO 


2.9 lExtentService 


Each instance of an EcoSpace contains an extent for every class in the model. If a request to lExtentService.Alllnstances is 
made, or if an OCL expression is evaluated that specifies "SomeClass.Alllnstances" an object locator will be created for 
every instance in the data storage and held in the extent service. Any subsequent request to the extent service for the same 
information will return this cached collection rather than accessing the data storage again. Access is only made to the data 
storage again if 


1. The extent for the specific class has not yet been requested for this EcoSpace instance. 

2. The extent service of the current EcoSpace has previously been instructed by the programmer to unload the extent for the 
specified class. 

Note that the extent service's state is unique per EcoSpace and not shared amongst multiple EcoSpaces. So if two 
EcoSpace instances request the extent for the same class they will both make a request to the data storage. 


The extend manages two pieces of information: 


2 


Type 

Description 

Alllnstances 

This is a list of object locators, one for each instance of the specified type. 

AllLoadedlnstances 

This again is a list of object locators. Instead of being one locator for every instance of the specified 
type it contains a list of all previously retrieved customer locators. 

For example, if you were to navigate to a customer via one of its purchase orders this would result in 
the customer's locator being added to the AllLoadedlnstances list for the Customer class. 


//Get all previously loaded customers 

int loadedCustomerCount = EcoSpace . Extents . AllLoadedlnstances (typeof (Customer )). Count ; 

//Get a locator list for all customers - data storage access is required 
IObjectList customerLocators = EcoSpace . Extents . Alllnstances (typeof (Customer )) ; 

//Get a locator list for all customers - not data storage access required 
IObjectList custoraerLocators2 = EcoSpace . Extents . Alllnstances (typeof (Customer) ) ; 


Unloading an extent 

An EcoSpace instance should be thought of as a unit of work, or as the equivalent of a database transaction. It is for this 
reason that the extents are cached, so that behaviour is predictable and to improve performance. There may sometimes be 
circumstances where you wish to invalidate the extent for a specific class. 
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//Invalidate the extent for Customer 

IClass classToUnload = (IClass) EcoSpace . TypeSystem. GetClassif ierByType (typeof (Customer) ) ; 
E co Space . Extents . Unload (classToUnload) ; 


If for example you are writing a WinForm application which has an ExpressionHandle with the expression 
"Customer.alllnstances", unloading the extent for the Customer class will cause the ExpressionHandle to reevaluate and 
display any new instances that may have been created by other users. Unloading the extent does not unload any objects' 
data contents. 


Subscribing to changes 

It is possible to subscribe to two events of the extent service. Using the SubscribeToObjectAdded method it is possible to 
register an observer which will be called back each time a new locator is added to the extent service. This could be due to 
creating a new instance of a class or due to loading an existing instance from the data storage. 


//A simple class to show a message box containing the class name 
//the locator added 

public class NewOb jectNotif ier : SubscriberAdapterBase 

of 

public NewOb jectNotif ier (object actualSubscriber ) 
: base (actualSubscriber) 

{ 


t 

protected override void DoReceive (object sender, EventArgs e, 
actualSubscriber) 

object 

1 

var args = (ElementChangedEventArgs ) e; 
MessageBox . Show (args . Element . UmlType . Name) ; 

} 


//Example usage 
//Create the subscriber 

var subscriber = new NewOb jectNotif ier (this) ; 


//Subscribe to locators being added for any class, this is achieved 
//using the "ECOModelRoot " class, which is the superclass of all 
//classes within the model. 

EcoSpace .Extents . SubscribeToObjectAdded (subscriber, "ECOModelRoot " ) ; 


To subscribe to locators being removed you may use the SubscribeToObjectRemoved. This method is almost the mirror of 
SubscribeToObjectAdded. Instead of triggering whenever an object is created or loaded the subscriber is triggered 
whenever an object is deleted. The trigger is executed as soon as customer.AslObject().Delete() is executed, rather than 
when a deleted object is updated using the persistence service (which causes the object locator to be relinquished). 


Note that the subscriber is not triggered when an extent is unloaded, nor when an object's contents are unloaded. Unloading 
an object's contents merely causes the local cached data values to be unloaded, it does not result in the EcoSpace 
relinquishing the locator for the object (the object's identity is still known). 
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2.10 IVersionService 


Using the version service via the IVersionService interface, the developer is able to retrieve historical information about 
objects that have been identified as "Versioned" in the ECO model. 


Object instances of classes that have been marked as Versioned are treated differently by the ECO persistence mechanism. 
By default each object within the database will have two additional columns, "TimeStampStart" and "TimeStampStop". 
These columns identify the life span of versioned objects. 


Each time UpdateDatabase is executed a new integer timestamp is value allocated, and the current date/time recorded 
against it. These integers are used to identify at which date/time a versioned object instance is created, modified, or deleted. 
When a new object instance is created the current timestamp is entered into its TimeStampStart column, and 2147483647 is 
entered into its TimeStampStop column, this records when the object came into existence, and the high TimeStampStop 
indicates that this row in the database is the current "live" data for the object. 


TimeStampStart 

TimeStampStop 

ECOJD 

FullName 

10 

2147483647 

5 

Miss Jane Smith 


When a versioned object is modified the TimeStampStop column of the live row is updated to the current timestamp value, 
and a new row is inserted into the table. This new row has the same ECOJD (the unique identifier for an ECO object 
instance), the current timestamp for TimeStampStart, and the new modified attribute values. 


TimeStampStart 

TimeStampStop 

ECOJD 

FullName 

10 

10 

5 

Miss Jane Smith 

11 

2147483647 

5 

Mrs Jane Jones 


Finally, when a versioned object is deleted, the TimeStampStop column of the live row is updated with the current timestamp 
- 1 . 


TimeStampStart TimeStampStop 

ECOJD 

FullName 

10 

10 

5 

Miss Jane Smith 

11 

11 

5 

Mrs Jane Jones 


To enable versioning on a class you must 

1 . Set Versioned = True on the class in the modeler. 

2. Set the following properties to True on the PersistenceMapper that your EcoSpace uses 

• UseClockLog 

• UseTimestampColumn 

• UseTimestampTable 

There is also a VersionGranularity property on the persistence mapper. If set to its default value time span of 00:00:00 a new 
version will be created for every call to UpdateDatabase. If set higher it is possible to instruct ECO to consider changes to 
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the same object within a specific window of time to be considered the same update, and not to create a new version of the 
object being updated. 


Retrieving a historical version of an object instance 

To retrieve a historical version of an instance you will first need to convert a specific date and time to a version number. 
Once you have the correct version number it is simple to retrieve the historical version of that object, all historical object 
versions are read only. 


//Specify the date and time 

var pointlnTime = new DateTime (...); 

//Convert the date/time to a version number 

int versionNumber = EcoSpace . Versioning . VersionAtTime (point InTime) ; 

Person personl = {Some code to get a customer instance) ; 

Person historical = 

EcoSpace . Versioning . GetVersion (versionNumber, 
customerl . AsIOb ject ( ) ) . GetValue<Person> ( ) ; 

MessageBox . Show (string . Format ( "Changed from {0} to {1}", 
historical . FullName, personl . FullName) ) ; 


Showing all changes to an object 

The GetChangePointCondition method creates an instance of AbstractCondition, which may then be used with the 
persistence service to retrieve a full history of an individual object. Starting from an ECO WinForms application add the 
following code to the constructor of your form. 
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/ /Create a person 

Person personl = new Person (EcoSpace) ; 

//Set the person's name and update the database 

personl . FullName = "Miss Jane Smith"; 

EcoSpace . UpdateDatabase ( ) ; 

//Sleep for 1 second 
Thread . Sleep ( 1000 ) ; 

//Change the person ' s name and update the database 
personl . FullName = "Mrs Jane Jones"; 

EcoSpace . UpdateDatabase ( ) ; 


Assuming you have correctly versioned the Person class and set up versioning on the EcoSpace's persistence this code will 
create two versions of a person when the application starts. To display this history in a WinForm DataGrid execute the 
following steps 


1. Set rhRoot.StaticValueTypeName to "Collection(Person)" - without the quotes. 

2. Add a DataGrid to your form, and use rhFtoot as its data source. 

3. Add the following additional code to the bottom of your form's constructor 

var condition = 

EcoSpace . Versioning . GetChangePointCondition ( 
rhRoot . Element , //Object to be retrieved 
0, //Earliest version to retrieve 
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EcoSpace . Versioning . CurrentVersion //Latest version to retrieve 

) ; 

//Retrieve all versions of this person 
IObjectList historicalVersions = 

EcoSpace .Persistence. GetAllWithCondition ( condition) ; 

//Set the reference handle to hold the list of versions 
rhRoot . SetElement (historicalVersions ) ; 


Running the application should give you a form that looks similar to the following illustration. Note that you cannot use the 
XML persistence for this example. 



Adding each version's date and time 

To show the date and time of each version we first need to add a code-derived column to the expression handle 

1 . Bring up the Columns editor on rhRoot. 

2. Click the drop-down arrow to the right of the "Add" button and select "EventDerivedColumn". 

3. Name the column VersionTimeStamp. 

4. Set its TypeName property to System. DateTime. 

5. Click OK. 

Now that the code-derived column has been added add the following code to the DeriveValue event of rhRoot. 


private void rhRoot_DeriveValue (object sender, DeriveEventArgs e) 

{ 

switch (e.Name) 

{ 

case "VersionTimeStamp" : 

//Get the current version number of the current row 
//Each row will have a different version number 

int versionNumber = EcoSpace . Versioning . ElementVersion (e . RootElement ) ; 
//Convert the version number to a date/time 

DateTime timestamp = EcoSpace .Versioning . TimeForVersion (versionNumber) ; 

//Set this date/time as the value to display in the data grid 
e . ResultElement = EcoSpace . VariableFactory . CreateConstant (timestamp) ; 

break; 


default : 

throw new NotlmplementedException (e .Name) ; 
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Once you have added the new column to the data grid you should see something like the following when you run the 
application. 



2.1 ICacheContentService 


2.1 Subscriptions 

When creating a business model it is often necessary to create members that have no persistent value but are instead 
calculated from other values. ECO supports this feature via "Derived" members. When creating a model it is possible to 
mark a property / association as Derived, indicating to ECO that the value needs to be calculated. When an attempt is made 
to read the value of a derived member ECO will perform the necessary actions to calculate its value. The calculated value is 
then stored away in the local cache, so that what it is read again no further calculations are required. 
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If calculating the value of the derived member is costly then storing the result in the cache will obviously save resources 
whenever the value is read again. However, if the calculated value where just to be stored away indefinitely it could easily 
become "stale." For example if Person. FullName were to be derived using the following OCL expression 


salutation + ' ' + givenName + ' ' + familyName 


If the value of any of these three members changes then rereading a stale cached value would result in an incorrect result. 
This is where the ECO subscription mechanism comes in. 


In the OCL derived member example above as ECO parses the OCL expression above in order to calculate the result it will 
need to access various members of the model; in this case Person. Salutation, Person. GivenName, and 
Person. FamilyName. Each derived member has its own "subscriber", as the ECO OCL evaluator accesses the value of a 
member it adds this subscriber to a list of parties interested in knowing when the member's value changes. 


Once the subscriptions have been placed with the relevant members and the result determined the derived member's value 
will be cached. Subsequent reads of the derived member will return the cached value. When one of the three members in 
the expression change they will notify every subscriber that has been registered with them. In this case the only subscriber 
will be the one owned by FullName, when this subscriber's Receive() method is executed it will invalidate its cached value. 
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Any subsequent attempt to read the value of the derived member will see that there is no cached value for it and cause the 
OCL evaluator to reprocess the expression and replace any required subscriptions. 


Subscribing to derived members 

A derived member may use any type of member as part of its calculated value. Associations, persistent members, transient 
members, and also other derived members. Take a simple class as an example, consisting of only three members. 


Name 

Type 

Derivation code 

Transientl 

Transient 


Derivedl 

Code 

derived 

private string Derivedl Derive() 

{ 

System. Diagnostics. Debug. WriteLine(" Model: Calculating Derivedl"); 
return "D1 + " + Transientl ; 

} 

Derived2 

Code 

derived 

private string Derived2Derive() 

{ 

System. Diagnostics. Debug. WriteLine(" Model: Calculating Derived2"); 
return "D2 + ” + Derivedl ; 

} 


now consider the following application code 


private void ReadDerivedl (Class_l instance) 

{ 

System . Diagnostics . Debug . WriteLine ( "App : Reading derivedl"); 

System . Diagnostics . Debug . WriteLine ( " Result = " + instance . Derivedl ) ; 

> 

private void ReadDerived2 (Class_l instance) 

{ 

System . Diagnostics . Debug . WriteLine ( "App : Reading derived2"); 

System . Diagnostics . Debug . WriteLine ( " Result = " + instance . Derived2 ) ; 

} 

private void ChangeTransient (Class_l instance, string value) 

{ 

System . Diagnostics . Debug . WriteLine ( "App : Changing transientl to " + value); 
instance . Transientl = value; 

} 


These instructions have only been made into methods in order to log how the application is using the domain object, and to 
make the steps easier to demonstrate. 


Step 

Instruction 

Output 

1 

ChangeT ransient(instance, 
"Hello world"); 

App: Changing transientl to Hello world 

2 

ReadDerivedl (instance); 

App: Reading derivedl 
Model: Calculating Derivedl 
Result = D1 + Hello world 
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3 

ReadDerived2(instance); 

App: Reading derived2 
Model: Calculating Derived2 
Result = D2 + D1 + Hello world 

4 

ChangeT ransient(instance, 
"Goodbye world"); 

App: Changing transientl to Goodbye world 

5 

ReadDerived2(instance); 

App: Reading derived2 
Model: Calculating Derived2 
Model: Calculating Derivedl 
Result = D2 + D1 + Goodbye world 


1 . The transient member has its value changed. This is just to start with a meaningful value. It has no effect on derived 
members as none of them have been accessed yet and therefore have not placed any subscriptions. 

2. The value of Derivedl is read. This calculation is based only on Transientl . The value is calculated and stored in the local 
cache. Derivedl places a subscription on Transientl. 

3. The value of Derived2 is read. This calculation is based only on Derivedl . When the value of Derivedl is read ECO sees 
that it has previously been calculated and cached, the calculation is not performed again, instead the cached value is 
returned. Derived2 places a subscription on Derivedl. 

4. The transient member is modified. As a consequence a change notification is sent to all of its subscribers. 

1 . Derivedl receives a notification that one of the members it has subscribed to has been modified. 

2. Derivedl invalidates its cached value. 

3. Derivedl notifies all of its subscribers that its value has possibly changed. 

4. Derived2 receives a notification that one of the members it has subscribed to has been modified. 

5. Derived2 invalidates its cached value. 

5. The value of Derived2 is read. 

1 . There is no cached value for Derived2 so its value is recalculated. 

2. Derived2 reads the value of Derivedl 

3. There is no cached value for Derivedl so its value is recalculated. 

4. DerivedTs value is cached. 

5. Derived2’s value is cached. 


2 


Auto subscription 

As mentioned previously the OCL evaluator will automatically subscribe to any members it accesses during evaluation of an 
expression. In the previous example however the values were accessed via source code and not an evaluator, so how were 
the subscriptions placed? 


All member values are stored in a local cache. Whenever a read/write is performed on a .NET instance of a modeled ECO 
class the property uses the local ECO cache to read/write the value. This means that ECO is fully aware of any time a value 
is touched, and as a result is able to identify which elements make up a derived member. When an attempt is made to 
access a derived member ECO performs the following steps 


1 . If there is a cached value. 

1 . Return the cached value. 

2. Finish. 

2. If the member has an OCL expression. 
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1 . Evaluate the expression. 

2. Place subscriptions on accessed elements. 

3. Store the result in the cache. 

4. Return the cached value. 

5. Finish. 

3. Find a method named <MemberName>Derive. 

1 . The members subscriber is pushed onto the lAutoSubscriptionService's stack. 

2. The <MemberName>Derive method is executed. 

3. Any access to an element in the cache checks the ActiveSubscriber in the auto subscription service, and registers it as 
a party interested in being notified when the element's value changes. 

4. The <MemberName>Derive method returns a result. 

5. The member's subscriber is removed from the auto subscription service's stack. 

6. Cache the result. 

7. Finish. 


2.1 ; ITypeSystemService 

The type system services allows your application to inspect your model in great detail at runtime. 


Short example - Identifying all classes used by an EcoSpace 

The first and most simple example shows how to identify all classes used by the EcoSpace. If the EcoSpace uses multiple 
class packages this list will include all classes of all packages used. 


2 



The output from the preceding source code (viewed in the Debug->Windows->Output window in Visual Studio) is as follows 


ECOModelRoot 

Customer 

Order 
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IModelElement 


OrderLine 

Product 

Product Category 

ProductCategoryProducts 

In the output you will see five class names you would expect to see after looking at the UML diagram for the model but there 
are two additional names you may not have expected, the first and last in the list. When ECO builds a runtime representation 
of your model it inspects it for a common superclass from which all classes ultimately descend, if no such class exists ECO 
will add an ECOModelRoot class which acts as an equivalent of System.Object for your model. 

The other unexpected class was ProductCategoryProducts. When you model a many to many association (in this case 
between Product and ProductCategory) ECO creates an implicit association class based on the name given to the 
association. You wont see a business class source file generated for this class, it is actually created as an embedded class 
of the package, this class exists only to provide additional meta-information to ECO at runtime and for creating database 
structures. Of course if you explicitly define an association class between Product and ProductCategory you will get a full 
business class generated in which you may define additional members. 


Changing the source code as follows 


foreach (iClass c in ecoSpace . TypeSystem . AllClasses ) 

Trace . WriteLine ( 

string . Format ( "Name= { 0 } Implicit={ 1 } IsLink= { 2 } " , 
c.Narae, c . Islmplicit, c . IsLinkClass ) 

) ; 


Will provide the following data, which I have formatted as a table. 


Name 

Implicit 

IsLink 

ECOModelRoot 

True 

False 

Customer 

False 

False 

Order 

False 

False 

OrderLine 

False 

False 

Product 

False 

False 

ProductCategory 

False 

False 

ProductCategoryProducts 

True 

True 


2 


In the following UML diagrams I have used the following colour scheme. 

1. Grey : Elements which are created once when the details of the runtime model is first established. 

2. Purple : Elements which hold meta information about values which may be created at runtime, such as variables and 
constants created by the IVariableFactoryService (a see page 18). 
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2.13.1 IModelElement 


•interface* 


•interface* 

1 Parameter 


1 Vertex 


•interface* 

IPackage 



•interface* 

IRegion 



•interface* 


•interface* 


•interface* 

lAssociation 


IModelElement 


IStateMachine 


•interface* 


•interface* 

1 Feature 


lEnumerationLiteral 


•interface* 


•interface* 

■Constraint 


ICIassifier 


The IModelElement interface is the base interface for almost all ECO model meta information. This interface allows you to 
determine the Name of the element, which Package it belongs to, and a collection of OCL constraints. The modeler also 
permits IModelElement descendants such as classes and their members to have tagged values (0 see page 151) assigned 
to them which may be read at runtime. 


2.13.* IPackage 


2 


« interfaces 

IModelElement 


« interface* 

IPackage 


A list of packages used by an EcoSpace may be obtained using from the EcoSpace.TypeSystem.AIIPackages property. 
Each package contains a collection of classes and associations that were modeled within it. 


foreach (IPackage package in ecoSpace . TypeSystem . AllPackages ) 
{ 


Debug . WriteLine ( 

string . Format (" ID={ 0 } Classes={l} Associat ions= { 2 } " , 

package. Id, package . Classes . Count , package . Associations . Count ) 

) ; 


The output from the preceding code would be something like 


ID= { SomeGUID } Classes=5 Associations=4 


Based on the simple Customer/Order model defined at the start of this section you will see there are five explicitly modeled 
classes and four associations. If you think back to the early source code example there were two additional classes 
ECOModelRoot and ProductCategoryProducts, these do not appear within the Classes collection because they were not 
explicitly modeled. Adding the following code within the above loop 
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foreach (IPackage package in ecoSpace . TypeSystem . AllPackages ) 

{ 

//Previous code omitted 

foreach ( IModelElement element in package . OwnedElements ) 

Debug . WriteLine ( 

string . Format ( " Element={0} Type={l}", element .Name, element . GetType (). Name ) 
) ; 

} 


Will result in the following output 


ID= { SomeGUID } Classes=5 Associations=4 
Element=Order Type=UmlClass 
Element=Product Category Type=UmlClass 
Element=OrderLine Type=UmlClass 
Element=Product Type=UmlClass 
Element=Customer Type=UmlClass 
Element=Order Customer Type=UmlAssociation 
Element=OrderLineOrder Type=UmlAssociation 
Element=OrderLineProduct Type=UmlAssociation 
Element=ProductCategoryProducts Type=UmlAssociation 


Note how ProductCategoryProducts is merely an association. This is because the information within an IPackage reflects 
how exactly how you modeled it. When ECO initialises its runtime model it is necessary to implicitly create items in order to 
make the model execute. For example I mentioned earlier how an ECOModelRoot class is created if there isn't a single 
common super class for all classes in a package, if the EcoSpace were to consume two modeled packages which had no 
dependencies upon each other then there couldn't possibly be a common super class. In this case ECO would certainly 
need to create an implicit super class (akin to a persistent System. Object), but which IPackage would this super class belong 
to? The answer is that it wouldn't belong to either. The IPackages' meta-information remains unaltered, it is the EcoSpace's 
run meta-information that hold this implicit class, along with implicit classes for associations. 


2 


The previous output lists five classes and four associations. The output from the following source code (which uses the 
EcoSpace's TypeSystem) 


foreach (iClass c in EcoSpace . TypeSystem. AllClasses) 
Debug . WriteLine ( "Class=" + c.Name); 


will show seven classes 


Class=ECOModelRoot 

Class=Customer 

Class=Order 

Class=OrderLine 

Class=Product 

Cl as s=Product Category 

Class=ProductCategoryProducts 


ECOModelRoot was added to the EcoSpace's runtime TypeSystem to cater for not having a common super class. In 
addition to having an association named ProductCategoryProducts there is also an implicit association class created. The 
reason this association class needs to exist is quite obvious. When changes are made to objects' state within an EcoSpace 
ECO identifies which instances' changes need to be persisted to the datastore by identifying each modified instance as 
"Dirty" (modified). When it comes to modifying associations in a one-to-one or a one-to-many association the ID of the linked 
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instance is stored in a single end of the association (e.g. the Order identity is embedded into the OrderLine). So adding an 
OrderLine to an Order will mark the OrderLine dirty and not the order, so ECO knows that only the OrderLine needs to be 
persisted to the datastore. 


There are two scenarios however where neither end of the association is considered dirty. In a many-to-many association 
neither side of the association is considered dirty because a database table can typically only hold single values, so neither 
side's database table can hold a collection of identities. In such a situation it is common practise when writing a database 
application to create a link table, consisting of two IDs (one for each side of the association). By creating the implicit class for 
a many-to-many association ECO is doing the same thing, not only does it identifying the fact that a link table is required 
within the database but it also enables ECO to identify which parts of the association are dirty (A1-B1 was removed, A1-B2 
was added). When modifying a many-to-many association only instances of this link-class are considered dirty. 


The other scenario is the case where neither side of an association is embedded. This means that the identity of neither side 
of the association is stored in the opposite side. In this case ECO will again create an implicit link class for storing the 
association. 


2.13.3 ITaggedValue 


ITaggedValue is a name/value pair of two strings. Anything implementing IModelElement has a collection of tagged values 
which may be obtained via its TaggedValues property. Elements such as classes, properties, and methods may be 
decorated with named values using the modeler during design time; these tagged values may then be read at runtime by the 
application. 
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For example if you select a class (Classl) in the model, click the TaggedValues editor, and then add a tagged value with the 
name "MyCompany.DisplayName" the tagged value could be read as follows 

ICIass c = EcoSpace . TypeSystem . GetClassByType (typeof (Classl )) ; 

ITaggedValue tv = c . GetltemByTag ( "MyCompany . DisplayName" ) ; 

SomeLabel . Text = tv. Value; 


2.13.4 IStructuralFeature 


A structural feature is anything on a class which holds state information. A method on a class holds no state and is therefore 
not a structural feature. Any modeled element on a class which produces a property in the generated code is considered a 
structural feature, this could be either an lAttribute or an lAssociationEnd. 


This interface provides information about the state holder such as whether it is persistent / derived / transient, if it is derived / 
derived settable, and the ICIassifier which represents the .NET type of the member. The members of IStructuralFeature , 
lAttribute, and lAssociationEnd are quite straight forward so wont be covered in this document, for more information about 
these interfaces please read the API documentation. 
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2.13.5 ICIass 


«interface» 

IModelElement 


•interface* 

•interface* 

ICIassifier 

IFeaturedType 


7 ^ 


y 

^-i 

•interface* 

ICIass 


The ICIass interface holds meta-information about classes. As an IModelElement it is possible to identify all tagged values 
assigned to it during modeling. 


Hierarchy 

ICIass has properties named SuperTypes and SubTypes. Although in .NET you can only descend your class from a single 
class the decision was made to make SuperTypes multiple in order to conform to the UML specification, SuperTypes will 
always contain zero or one entries. SubTypes on the other hand may obviously contain any number of entries. 



Given the previous model it is possible to map the structure at runtime using the following recursive source code. 
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public void OutputEcoSpaceHierarchy ( ) 

{ 

//Only if we have at least one class 
if (EcoSpace . TypeSystem. AllClasses . Count > 0) 

//Output the super class 

Out put Cl ass Hierarchy ( 0 , EcoSpace . TypeSystem. AllClasses [ 0 ] ) ; 

} 

private void OutputClassHierarchy (int indent, ICIass currentClass) 
f 

string indentText = new string (' indent); 

Debug . WriteLine ( indentText + currentClass . Name ) ; 

//Output each sub type 

foreach (ICIass childClass in currentClass . SubTypes ) 
OutputClassHierarchy ( indent + 2, childClass); 

} 


This code would result in the following ouptut 


MyExplicit Superclass 
ChildClassl 
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GrandChildClassl 

GrandChildClass2 

ChildClass2 

GrandChildClass3 

GrandChildClass4 


The AllClasses property is always sorted into a hierarchical order. A sub type will never have a lower index in the collection 
than its super type, ultimately the ICIass at index zero will always be the root class for the entire runtime model, whether it is 
implicitly created or explicitly created as in this example. 


Model hierarchy 



In addition to being an IModelElement the ICIass interface also descends from IFeaturedType. This type is used for modeled 
classes and for adhoc query classes when executing a query in OCL or LINQ which returns a tuple (collection of data rather 
than instances of modeled types). 
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Using the IFeaturedType.AIIStructuralFeatures property and the ICIass. AIIMethods properties it is possible to determine the 
structure of a class. 


public void ShowOrderClassStructure ( ) 

{ 

Output Cl ass Structure ( E coSpace . TypeSystem .AllClasses. Get ItemByName ( "Order " ) ) ; 

} 

private void OutputClassStructure ( ICIass currentClass ) 

{ 

foreach (IFeature feature in currentClass . AllStructuralFeatures ) 
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{ 

Debug . WriteLine ( 

string . Format ( "Feature - {0} {1} {2}", 
feature. Visibility, 
feature .Name, 
feature . FeatureType) 


foreach (IMethod method in currentClass . AllMethods ) 
{ 

Debug . WriteLine ( 

string . Format ("{ 0 } {1}", 
method .Visibility, 
method . Name) 


Output 


Feature - Public_ Customer AssociationEnd 
Feature - Public_ OrderLines AssociationEnd 
Feature - Public_ Number Attribute 
Feature - Public_ TotalValue Attribute 
Method - Public_ AddProduct 
Method - Public_ RemoveProduct 


Association classes 

If the class reference is an association class, either implicit or explicit, its Association property will identify the association it 
represents. 


2 



With a reference to the FoodAllergy's ICIass it is possible to obtain the lAssociation reference it represents and obtain 
additional information about the association; such as whether the association is derived / transient / persistent, or to obtain 
information about the classes at either end of the association (Person / Food) and the multiplicity of the association ends. 
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•interface* 

IStructuralFeature 
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•interface* 

■Attribute 

lAssociationEnd 



When accessing ICIass.AIIStructuralFeatures the result will contain structural features modeled in the class and all structural 
features it inherits from its ancestor classes. Iterating this collection of IStructuralFeature will give every structural feature 
available to the class, if you wish to iterate only structural features introduced by the current you can use the 
FirstOwnStructuralFeaturelndex property. 


ICIass c = EcoSpace . TypeSystem . GetClassByType (typeof (BaseClass ) ) ; 

for (int i = c . FirstOwnStructuralFeaturelndex; i < c . AllStructuralFeatures . Count ; i++) 
{ 

IStructuralFeature f = c . AllStructuralFeatures [ i ] ; 

Console .WriteLine (f. Name ) ; 

} 


Class meta-data example 

This example uses the previous Customer/Order model. 
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//Code omitted 

ICIass c = EcoSpace . TypeSystem. GetClassByType (typeof (Order) ) ; 
OutputClassInfo (c) ; 


A class is considered to be either Persistent or Transient, c. Persistent reflects the persistence state of the class. The 
DefaultStringRepresentation is the expression that is evaluated whenever the "asString" OCL expression is evaluated 
against an object instance. 


private void OutputClassInfo ( ICIass c) 
/ 


Console . WriteLine ( "Name : {0}", c.Name); 

Console . WriteLine ( " Persistent : {0}", c . Persistent ) ; 

Console . WriteLine ( " DefaultStringRepresentation : {0}", 

c . DefaultStringRepresentation) ; 

Console . WriteLine ( " Methods"); 
OutputClassMethods (c) ; 


Console .WriteLine (" Attributes " ) ; 
OutputClassAttributes (c) ; 


Console . WriteLine ( " Association ends") ; 
OutputClassAssociationEnds (c) ; 

} 



[Output ] 


Name : Order 


Persistent : True 


DefaultStringRepresentation 

self . Number 


ICIass. AIIMethods contains method information for each modeled method on the class. This will contain inherit methods, but 
not methods which were not added via the modeler. 


private void OutputClassMethods ( ICIass c) 

{ 

foreach (IMethod m in c .AIIMethods) 

( 

Console . WriteLine ( " Name : {0}", m.Name); 

if (m. ReturnType != null) 

Console . WriteLine ( " Returns : {0}", m . ReturnType . Name ) ; 

else 

Console . WriteLine ( " Returns : void"); 

OutputMethodParameters (m) ; 



private void OutputMethodParameters ( IMethod m) 

{ 

foreach (IParameter p in m . Parameters ) 

Console . WriteLine ( " Parameter {0} of type {1} - direction {2}", m.Name, 

p. Type. Name, p.Kind); 

} 


[Output ] 

Methods 

Name : AddProduct 
Returns : void 
Parameter AddProduct 


of type Product 


direction In 
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Name : RemoveProduct 
Returns : void 

Parameter RemoveProduct of type Product - direction In 


As with AIIMethods only members added to the class via the modeler will appear in AIIStructuralFeatures. The list will 
contain both inherited and introduced members. The output of the following code is the result of inspecting the OrderLine 
class rather than the Order class, because the OrderLine class has a derived member. The AIIStructuralFeatures list will 
contain both lAttributes and lAssociationEnds, the example code filters the list to show only lAttributes using the LINO 
"OfType" filter. 


private void OutputClassAttributes ( ICIass c) 

{ 

foreach (IAttribute a in c . AllSt ructuralFeatures . Of Type<IAtt ribute> ( ) ) 

{ 

Console . WriteLine ( " Name : {0} of type {1}", a. Name, a . Type_. Name ) ; 

Console . WriteLine ( " Persistent : {0}", a . Persistent ) ; 

if (a . IsDerived) 

{ 

Console . WriteLine ( " Derived and settable : {0}", a . IsReverseDerived) ; 

if (a . DeriveAndSubscribeMethod != null) 

Console . WriteLine ( " Derived using method : {0}", 

a . DeriveAndSubscribeMethod . Name) ; 

else 

Console . WriteLine ( " Derived using expression : {0}", 

a . TaggedValues . Get ItemByTag ( "Eco . DerivationOCL" ) .Value ) ; 



[Output ] 

Attributes 

Name : ProductPrice of type System . Decimal 
Persistent : True 

Name : LineValue of type System. Decimal 
Persistent : False 
Derived and settable : False 

Derived using expression : quantityOrdered * productPrice 

Name : QuantityOrdered of type System. Int32 
Persistent : True 


2 


The following code outputs meta information about lAssociationEnds on the Order class. As with the previous IAttribute 
example the list is filtered using LINQ. 


private void OutputClassAssociationEnds (ICIass c) 

{ 

foreach ( IAssociationEnd a in c . AIIStructuralFeatures . Of Type<IAssociationEnd> () ) 

{ 

Console . WriteLine ( " Name : {0}", a. Name); 

Console . WriteLine ( " Persistent : {0}", a . Persistent ) ; 

if (a . IsDerived) 

{ 

Console . WriteLine ( " Derived and settable : {0}", a . IsReverseDerived) ; 

if (a . DeriveAndSubscribeMethod != null) 

Console . WriteLine ( " Derived using method : {0}", 

a . DeriveAndSubscribeMethod . Name) ; 

else 

Console . WriteLine ( " Derived using expression : {0}", 

a . TaggedValues . Get ItemByTag ( "Eco . DerivationOCL" ) .Value ) ; 

} 
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Console . WriteLine ( " Navigable : {0}", a . IsNavigable) ; 

Console . WriteLine ( " Multiplicity : {0}..{1}", a . Multiplicity . Lower , 

a . Mult iplicity . Upper ) ; 



[Output ] 

Association ends 
Name : Customer 

Persistent : True 
Navigable : True 
Multiplicity : 1..1 
Name : Lines 

Persistent : True 
Navigable : True 
Multiplicity : 0 .. 2147483647 


If the association where derived the output would reveal how it is derived, either as an OCL expression or via a method call. 
In addition it would also indicate whether the member is derived and settable (IsReverseDerived). This is also available on 
lAttribute as it is inherited from IStructuralFeature. 


2 
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4 Replacing standard ECO services 


4.1 Replacing the ExternalldService 


4.2 A validating IPersistenceService 

Constraints in ECO are not enforced by default. This is because it is up to the application developer to decide when to 
evaluate constraints and also how to handle constraints when they are broken. One approach is to prevent the user from 
saving changes when there are broken constraints, however a sensible backup strategy is to ensure there are no broken 
constraints when the datastorage is updated; this protects the persistent data from becoming corrupted if the application 
developer neglects to enforce constraints at a single point in the application. 


The easiest way to replace the IPersistenceService for an EcoSpace is to descend a new class from the 
ChainedPersistenceServiceBase class. In this following code sample you will see the following 


1. A constructor is added accepting the lEcoServiceProvider. This is done so that references to other services may be 
obtained where necessary. 

2. The NextPersistenceService property is set. This ensures that all persistence requests are passed on to the real 
implementer. 

3. UpdateDatabaseWithList<T> is overridden. This is so that the objects being updated may be validated first. 

This method uses the DroopyEyes.EcoExtensions. Validation. ModeledConstraintProvider class to obtain constraints for a 
given instance, this class is used to simplify the example. 


public class ValidatingPersistenceService : ChainedPersistenceServiceBase 
f 

readonly lEcoServiceProvider ServiceProvider; 

public ValidatingPersistenceService (lEcoServiceProvider ServiceProvider) 

: base ( ) 

{ 

if (ServiceProvider == null) 

throw new ArgumentNullException ( "ServiceProvider" ) ; 

//Save the service provider reference, and set NextPersistenceService 

ServiceProvider = ServiceProvider; 

NextPersistenceService = ServiceProvider . GetEcoService<IPersistenceService> () ; 

} 

public override void UpdateDatabaseWithList<T> ( IEnumerable<T> list) 

{ 

var constraintProvider = new ModeledConstraintProvider () ; 
foreach (IObject instance in list) 

< 

//Ignore deleted objects 
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if ( instance . Deleted) 
continue ; 


//Get a list of IConstraint instances for the object being 

updated 

var constraints = new List<IConstraint>(); 

constraintProvider . GetConstraintsForOb ject (instance, constraints) ; 

//Find the first broken constraint 

var brokenConstraint = constraints . FirstOrDef ault (c => !c. 

IsValid) ; 

//If a constraint is broken throw an exception showing the 
//object class + the constraint name 

if (brokenConstraint != null) 

throw new Exception ( instance . AsOb ject . GetType (). Name + 
brokenConstraint .Name) ; 

II . II i 

; 

base . UpdateDatabaseWithList<T> (list) ; 

} 

} 



To install the service register it when the EcoSpace becomes active by overriding the Active property. 


public override bool Active 

{ 

get 

{ 

return base. Active; 

} 

set 

{ 

base. Active = value; 
if (Active) 

RegisterEcoService<IPersistenceService> (new 
ValidatingPersistenceService (this) ) ; 

} 

} 


When an attempt is made to call UpdateDatabase on an EcoSpace where one of the objects has a broken constraint an 
exception will be thrown with a message similar to 


Person : FullName required 
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